Introduction

This document codifies the standard algorithms used by grade school students for rational numbers, equality, inequality, and arithmetic. It originally started as a pre-algebra refresher and instead morphed into what it is now.

Place Value System

The place value system is the modern way in which numbers are represented. A number represented using the place value system is made up of a string of symbols separated by a dot, where each (index, symbol) combination in the string represents a value (i.e. val[idx] = compute(idx, str[idx])).

The symbols used to represent a number are called digits. All digits to the...

• left of the dot represents entire objects, called the whole part.
• right of the dot represents a partial object, called the fractional part.

These wholes and fractional are combined to represent the final value for the number. For example, the number 43.5 represents...

●●●●●●●●●●
●●●●●●●●●●
●●●●●●●●●●
●●●●●●●●●●  ●●●     ◑
    4        3   .  5

The grammar for the place value system is...

number: whole (DOT fractional)?;
whole: DIGIT+;
fractional: DIGIT+;

DOT: '.';
DIGIT: [0123456789];

The entry point to the grammar is the number rule. Note that the fractional part of the number rule is optional -- a number with a missing fractional part is assumed to have no partial value -- it consists of only entire objects.

The whole rule is used to express how many entire objects there are. The algorithm for determining that value consists of 3 steps:

1. Determine the value each digit represents...

   0 = <empty>
   1 = ●
   2 = ●●
   3 = ●●●
   4 = ●●●●
   5 = ●●●●●
   6 = ●●●●●●
   7 = ●●●●●●●
   8 = ●●●●●●●●
   9 = ●●●●●●●●●
   

   These are the digits and their values.

2. Then, calculate the value for each index of the whole part. The algorithm for determining the value of each index is...

   index_values = []
   for (item in index) {
     next_index_value = <empty>
     if (index_values.isEmpty()) {
       index_values.push(●)
     } else {
       last_index_value = index_value[-1]
       for (inner_item in ●●●●●●●●●●) {   // the number of dots here should be 1 more than the value of the largest symbol
         next_index_value.push(last_index_value)
       }
     }
   }
   index_values.reverse()
   

   For example, the index values in the whole part 572 are...

   _ _ _
   │ │ │
   │ │ └─ ● 
   │ └─── ●●●●●●●●●●
   └───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

3. Now that the digit values and index values are known, the value of each (digit, index) combination can be calculated. The algorithm for determining the value of each (digit, index) combination is...

   final_value = <empty>
   for (digit_value, index_value) in input
     value = <empty>
     for item in digit_value
       value.push(index_value)
   

   For example, the (digit, index) values in the whole part 572 are....

   • 5__

     ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
     ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
     ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
     ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
     ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
     

   • _7_

     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     

   • __2

     ●
     ●
     

   Those values combined together would be...

   5 7 2
   │ │ │
   │ │ └─ ●
   │ │    ● 
   │ │
   │ └─── ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │
   └───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

The fractional rule is used to express some portion of an object (less than a single object). Conceptually, you can think of each digit in the fractional string as a recursive slicing of a single whole. For example, in the fractional string 358, the first index picks out 3 equal parts out of the whole ...

, ... the second index picks out 5 equal parts out of the NEXT part of the whole ...

, ... the third index picks out 8 equal parts out of the NEXT part of the previous part ...

.

This is exactly the same as chopping up a whole into 1000 equal parts and picking 358 of those parts...

The algorithm for processing the fractional rule is similar to the conceptual model described above. It consists of 2 steps:

1. Determine the total number of parts there are. The algorithm for this is...

   total_parts = <empty>
   for (item in index) {
     if (total_parts == <empty>) {
       total_parts.push(●●●●●●●●●●) // the number of dots here should be 1 more than the value of the largest digit
     } else {
       new_total_parts = <empty>
       for (inner_item in ●●●●●●●●●●) {  // the number of dots here should be 1 more than the value of the largest digit
         new_total_parts.push(total_parts)
       }
       total_parts = new_total_parts
     }
   }
   

   For example, for a fractional part of 55 the total number of parts would be 100...

   ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

   ⚠️NOTE️️️⚠️

   An easier way to do the same thing is...

   1. add an extra index.
   2. set the first index to 1.
   3. set all other indexes to 0.

   So if the fractional string has 2 digits (as 55 does), the total number of parts would be 100.

   The reason why the code above doesn't do this is because I'm trying to avoid the use of numbers and operations that haven't been introduced yet.

   ⚠️NOTE️️️⚠️

   Know exponents? Doing 10^fractional.length is the same thing.

   If the fractional string has 2 digits (as 55 does), the total number of parts would be 10^2=100.

   The reason why the code above doesn't do this is because I'm trying to avoid the use of numbers and operations that haven't been introduced yet.

2. The fractional string is a selection out the total parts calculated in the step above.

   For example, for a fractional part of 55, ...

   [●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●]●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

   

Similar to the sliced circle diagrams shown in the algorithm descriptions above, a number line may also be used to visualize the value that a number represents. It consists of a straight horizontal line with equidistant vertical notches spliced through out, where each notch is labelled with incrementally larger numbers from left-to-right...

The number being represented is marked on the line. For example, to represent the number 5...

Numbers with fractional parts may also be marked on the line. Move the marker to the whole part of the number, then determine the amount of space that the fractional part consumes and move over that much towards the next notch. For example, to represent the number 5.5...

First, move the marker over to the whole: 5...

Then, determine how much space in the fractional part was consumed. 5.5's fractional part takes up half a circle, so it gets moved half way towards the next notch...

Equality

Equality is the concept of checking if one number to see if it has the same value as another number. In other words, checking if both numbers are the same. For example, the numbers 5 and 5 are the same number, so they're said to be equal.

If you were to visualize both numbers on a number line, they would both sit at the same position...

Equality is typically represented using the infix operator = or ==. The above example would be represented as 5=5.

The output of an equality operation is either true or false: true when the numbers are the same and false when they aren't. For example, ...

• 5 = 5 is true because the numbers are the same.
• 5 = 7 is false because the numbers aren't the same.

When using words, equality is typically represented using the following syntax:

• equal -- e.g. 5 equals 5
• is -- e.g. 5 is 5
• was -- e.g. 5 was 5
• will be -- e.g. 5 will be 5
• the same -- e.g. 5 and 5 are the same
• gives -- e.g. performing the operation gives 5

The opposite of equality is not equality. That is, not equality is the concept of checking if one number has a different number of items than another number. For example, the numbers 5 and 6 are different, so they're said to be not equal.

Not equality is typically represented using the infix operator ≠ or !=. The above example would be represented as 5≠6.

The output of a not equality operation is either true or false: true when the numbers are different and false when they're the same. For example, ...

• 5 ≠ 7 is true because the numbers are different.
• 5 ≠ 5 is false because the numbers are the same.

When using words, not equality is typically represented using the following syntax:

• not equal -- e.g. 6 is not equal to 5
• is not -- e.g. 6 is not 5
• was not -- e.g. 6 was not 5
• won't be -- e.g. 6 won't be 5
• not the same -- e.g. 6 and 5 are not the same
• does not give -- e.g. performing the operation does not give 5

Greater Than

Greater than is the concept of checking if one number represents more items than another number. For example, the number 8 has more items than the number 5, so 8 is said to be greater than 5.

If you were to visualize both numbers on a number line, the number 8 would be ahead of 5...

Greater than is typically represented using the infix operator >. The above example would be represented as 8>5.

The output of a greater than operation is either true or false: true when the first number has more items and false when it doesn't. For example, ...

• 8 > 5 is true because the first number (8) has more items.
• 5 > 5 is false because the first number (5) doesn't have more items.

When using words, greater than is typically represented using the following syntax:

• greater than -- e.g. 8 is greater than 5
• larger than -- e.g. 8 is larger than 5
• more than -- e.g. 8 is more than 5

Greater than or equal is common shorthand to compare if a number is greater than or equal to some other number. It's typically represented using the infix operator ≥ or >=. For example...

• 8 ≥ 5 is true because the first number (8) has more items.
• 5 ≥ 5 is true because the first number (5) has equal items.
• 4 ≥ 5 is false because the first number (4) has less items.

When using words, greater than or equal is typically represented using the following syntax:

• greater than or equal -- e.g. 8 is greater than or equal to 5
• larger than or equal -- e.g. 8 is larger than or equal to 5
• more than or equal -- e.g. 8 is more than or equal to 5
• at least -- e.g. 8 is at least 5

Less Than

Less than is the concept of checking if one number has fewer items than another number. For example, the number 5 has fewer items than the number 8, so 5 is said to be less than 8.

If you were to visualize both numbers on a number line, the number 5 would be behind of 8...

Less than is typically represented using the infix operator <. The above example would be represented as 5<8.

The output of a less than operation is either true or false: true when the first number has fewer items and false when it doesn't. For example, ...

• 5 < 8 is true because the first number (5) has fewer items.
• 5 > 5 is false because the first number (5) doesn't have fewer items.

When using words, less than is typically represented using the following syntax:

• less than -- e.g. 5 is less than 8
• smaller than -- e.g. 5 is smaller than 8
• fewer than -- e.g. 5 is fewer than 8

Less than or equal is common shorthand to compare if a number is less than or equal to some other number. It's typically represented using the infix operator ≤ or <=. For example...

• 5 ≤ 8 is true because the first number (5) has less items.
• 5 ≤ 5 is true because the first number (5) has equal items.
• 5 ≤ 4 is false because the first number (5) has more items.

When using words, less than or equal is typically represented using the following syntax:

• less than or equal -- e.g. 8 is less than or equal 5
• smaller than or equal -- e.g. 8 is smaller than or equal 5
• fewer than or equal -- e.g. 8 is fewer than or equal 5
• at most -- e.g. 5 is at most 8

Addition

Addition is the concept of taking two numbers and combining their values together. For example, combining 3 items and 5 items together results in 7 items...

 [●●●]    [●●●●●]
   3         5

group values together

   [●●●●●●●●]
       7

Addition is typically represented using the infix operator +. The above example would be represented as 3+5.

The output of an addition operation is called the sum. In the example above, 7 is the sum.

When using words, addition is typically represented using the following syntax:

• addition -- e.g. the addition of 3 and 5
• add -- e.g. add 3 and 5
• plus -- e.g. 3 plus 5
• sum -- e.g. sum of 3 and 5
• increase -- e.g. 3 increased by 5
• more than -- e.g. 3 more than 5
• larger than -- e.g. 3 larger than 5
• greater than -- e.g. 3 greater than 5
• total -- e.g. total of 3 and 5

Properties of addition:

• Order in which 2 numbers are added doesn't matter (commutative).

   [●●●]    [●●●●●] results in [●●●●●●●●]    (3+5 is 7)
     3         5                    7
  
   [●●●●●]   [●●●]  results in [●●●●●●●●]    (5+3 is 7)
     5         3                    7
  

• Any number plus 0 results in the same number (identity).

  [●●●]    [] results in [●●●]    (3+0 is 3)
    3       0              3
  
  []    [●●●] results in [●●●]    (0+3 is 3)
   0      3                3
  

Subtraction

Subtraction is the concept of removing the value of one number from another number. For example, removing 3 items from 5 items results in 2 items...

    [●●●●●]
       5

pick out 3 from the 5

   [●●] [●●●]
    2     3

Subtraction is typically represented using the infix operator -. The above example would be represented as 5-3.

The output of an subtraction operation is called the difference. In the example above, 2 is the difference.

When using words, subtraction is typically represented using the following syntax:

• subtraction -- e.g. the subtraction of 3 and 5
• minus -- e.g. 5 minus 3
• difference of -- e.g. difference of 5 and 3
• subtracted by -- e.g. 5 subtracted by 3
• decreased by -- e.g. 5 decreased by 3
• less than -- e.g. 3 less than 5
• fewer than -- e.g. 3 fewer than 5
• smaller than -- e.g. 3 smaller than 5
• subtracted from -- e.g. 3 subtracted from 5

Properties of subtraction:

• Any number subtracted by 0 results in the same number (identity).

  [●●●]    [] results in [●●●]    (3+0 is 3)
    3       0              3
  

Multiplication

Multiplication is the concept of taking a number and iteratively adding it to itself a certain number of iterations. For example, 3 added to itself for 5 iterations results in 15 items...

3+3+3+3+3=15

 [●●●] 3
 [●●●] 3
 [●●●] 3
 [●●●] 3
 [●●●] 3

Multiplication is typically represented using the infix operator *. The above example would be represented as 3*5. When written in formal math notation, it may also be written as...

• $3 \cdot 5$
• $3(5)$
• $(3)5$

The output of a multiplication operation is called the product. In the example above, 15 is the product.

The inputs into the multiplication operation are either...

• called factors -- in the example above, 3 and 5 are the factors,
• or the first input is called the multiplier and the second input is called the multiplicand -- in the example above, 3 is the multiplier and 5 is the multiplicand.

When using words, multiplication is typically represented using the following syntax:

• multiplication -- e.g. the multiplication of 3 and 5
• multiply -- e.g. multiply 3 and 5
• multiplied -- e.g. 3 multiplied by 5
• times -- e.g. 3 times 5
• product of -- e.g. the product of 3 and 5

Properties of multiplication:

• Order in which 2 numbers are multiplied doesn't matter (commutative).

   3*5       vs     5*3
  ┌───┐            ┌┬┬┬┐
  ├●●●┤3           │●●●│
  ├●●●┤3           │●●●│
  ├●●●┤3           │●●●│
  ├●●●┤3           │●●●│
  ├●●●┤3           │●●●│
  └───┘            └┴┴┴┘
                    555
  
  the number of dots is the same
  

• Any number multiplied by 0 is 0.

  This makes sense if you think of multiplication as iterative addition...

  var product = 0;
  for (var i = 0; i < multiplicand; i++) {
      product += multiplier;
  }
  

  If you iterate 0 times, the product will be 0.

• Any number multiplied by 1 results in that same number (identity).

  3*3=3+3+3
  3*2=3+3
  3*1=3 -- 3 is just by itself, it isn't being added
  

Division

Division is the concept of taking a number and iteratively subtracting it by another number to find out how many iterations it can be subtracted. For example, 15 can be subtracted by 3 exactly 5 iterations before nothing's left...

 [●●●●●●●●●●●●●●●] start with 15

 [●●●●●●●●●●●●] 15-3=12 (iteration 1)
 [●●●●●●●●●] 12-3=9 (iteration 2)
 [●●●●●●] 9-3=6 (iteration 3)
 [●●●] 6-3=3 (iteration 4)
 [] 3-3=0 (iteration 5)

Another way of thinking about division is that it's chopping up a number. Imagine cutting up a pie into 15 pieces and eating 3 pieces at a time. The pie will be done after you've eaten 5 times.

In certain cases, division may result in some remaining value that isn't large enough for another subtraction iteration to take place. This remaining value is called the remainder For example, 16 can be subtracted by 3 for 5 iterations but will have a remainder of 1...

 [●●●●●●●●●●●●●●●●] start with 16

 [●●●●●●●●●●●●●] 16-3=13 (iteration 1)
 [●●●●●●●●●●] 13-3=10 (iteration 2)
 [●●●●●●●] 10-3=7 (iteration 3)
 [●●●●] 7-3=4 (iteration 4)
 [●] 4-3=1 (iteration 5)

 only 1 item left -- not enough for another subtraction iteration
 
 1 is the remainder

Division is typically represented using the infix operator / or ÷. The above example would be represented as 15/3 or 15÷3. It may also be written as $\frac{15}{3}$, which is just a fancier way of writing 15/3.

The output of a division operation is called the quotient. In the example above, the quotient is 5 (it subtracts 5 times).

The inputs into the division operation are called the dividend and divisor. In the example above, 15 is the dividend and 3 is the divisor.

• $dividend \div divisor = quotient$
• $dividend / divisor = quotient$
• $\frac{dividend}{divisor} = quotient$

When using words, division is typically represented using the following syntax:

• division -- e.g. the division of 3 and 15
• divide -- e.g. divide 3 by 15
• divided by -- e.g. 3 divided by 15
• divided into -- e.g. 15 divided into 3
• quotient of -- e.g. the quotient of 3 and 15

Properties of division:

• Any number divided by 1 results in the same number (identity).

  [●●●●●] start with 5
  
  [●●●●] 5-1=4 (iteration 1)
  [●●●] 4-1=3 (iteration 2)
  [●●] 3-1=2 (iteration 3)
  [●] 2-1=1 (iteration 4)
  [] 1-1=0 (iteration 5)
  
  5 iterations total
  

• Any number divided by itself is 1.

  [●●●●●] start with 5
  
  [] 5-5=0 (iteration 1)
  
  1 iteration total
  

• Any number divided by 0 is infinity.

  This makes sense if you think of division as iterative subtraction...

  quotient = 0
  while dividend >= divisor:
      dividend -= divisor
      quotient += 1
  

  This will iterate forever if the divisor is 0 because the dividend would never become less than the divisor -- the loop wouldn't terminate.

  ⚠️NOTE️️️⚠️

  Another way to think of this is that division is the inverse of multiplication (it undoes multiplication). If it were the case that 10/0=?, then ?*0=10. We know that this can't be the case because ?*0=0.

Whole Number

Whole numbers are numbers which have no fractional part -- they only consist of wholes. For example, 5, 0, 104, and 27 are whole numbers while 4.2 is not.

The difference between whole numbers and natural / counting / cardinal numbers is that counting numbers don't include 0 (they start at 1). That is, counting numbers start where you start counting / where something exists. For example, if you're counting apples, you start counting at 1 -- there needs to be at least 1 apple to start.

Equality

The algorithm used by humans to test for whole number equality relies on two idea...

1. If two whole numbers are equal then they must have the same number of digits. For example, 55 and 9123456 aren't equal because the number of digits between them isn't the same -- 55 has 2 digits while 9123456 has 7 digits.

   ⚠️NOTE️️️⚠️

   This assumes that any prepended 0 digits have been removed. Recall that 07, 007, 0007, ... all represent the same value: 7.

2. Numbers represented in place-value notation can be broken down into single digit components -- the place of each digit in the number represents some portion of that number's value. For example, the number 935 can be broken down as 9 100s, 3 10s, and 5 1s...

   100
   100
   100
   100
   100            1
   100            1
   100     10     1
   100     10     1
   100     10     1
   ---     --     -
   900     30     5
   
   
   
   9 3 5
   │ │ │
   │ │ └─ ●
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │
   │ └─── ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │
   └───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

Since the numbers being tested for equality must have the same number of digits between them, the first test to see if they may be equal is to a ensure that the number of digits are equal (idea 1). For example, 55 has 2 digits while 9123456 has 7 digits -- there's no point in going any further because if the number of digits aren't the same then there's no way for the actual numbers to be the same.

If it turns out that the number of digits are the same, then each place's digit is tested for equality (idea 2). If all the digits are equal, then the numbers are equal. For example, the numbers 195 and 195 are equal...

1 9 5
| | |
1 9 5

... while the numbers 175 and 195 are not equal...

1 7 5
| x |
1 9 5

The way to perform this algorithm via code is as follows...

arithmetic_code/WholeNumber.py (lines 139 to 158):

@log_decorator
def __eq__(lhs: WholeNumber, rhs: WholeNumber) -> bool:
    if isinstance(rhs, int):
        rhs = WholeNumber.from_int(rhs)
    elif isinstance(rhs, str):
        rhs = WholeNumber.from_str(rhs)

    if not isinstance(rhs, WholeNumber):
        raise Exception()

    log(f'Equality testing {lhs} and {rhs}...')
    log_indent()

    ret = lhs.digits == rhs.digits

    log_unindent()
    log(f'{ret}')

    return ret

Less Than

The algorithm used by humans to test for whole number less than relies on the idea that numbers represented in place-value notation can be broken down into single digit components -- the place of each digit in the number represents some portion of that number's value. For example, the number 935 can be broken down as 9 100s, 3 10s, and 5 1s...

100
100
100
100
100            1
100            1
100     10     1
100     10     1
100     10     1
---     --     -
900     30     5



9 3 5
│ │ │
│ │ └─ ●
│ │    ● 
│ │    ● 
│ │    ● 
│ │    ● 
│ │
│ └─── ●●●●●●●●●●
│      ●●●●●●●●●●
│      ●●●●●●●●●●
│
└───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●

Since a number can be broken down into single digit components, each single digit component from the numbers being compared can individually tested from most significant to least significant (left-to-right). If a digit from the number being tested is...

• less than the corresponding digit from the number being tested against, the number being tested is less than (algorithm ends).
• greater than the corresponding digit from the number being tested against, the number being tested is greater than (algorithm ends).
• equal to the corresponding digit from the number being tested against, continue to testing the next digit.

If no more digits are remaining for testing, the number being tested is equal.

For example, imagine testing the number 23 and 21...

2 3                      2 1
│ │                      │ │
│ └─ ●                   │ └─ ●
│    ●                   │
│    ●                   └─── ●●●●●●●●●●
│                             ●●●●●●●●●●
└─── ●●●●●●●●●●
     ●●●●●●●●●●

The first digits are equal (2 == 2), so move to the next digit. The next digit is larger than the other digit (3 > 1), so 23 is not less than 21.

The way to perform this algorithm via code is as follows...

arithmetic_code/WholeNumber.py (lines 161 to 188):

@log_decorator
def __lt__(lhs: WholeNumber, rhs: WholeNumber) -> bool:
    if isinstance(rhs, int):
        rhs = WholeNumber.from_int(rhs)
    elif isinstance(rhs, str):
        rhs = WholeNumber.from_str(rhs)

    if not isinstance(rhs, WholeNumber):
        raise Exception()

    log(f'Less than testing {lhs} and {rhs}...')
    log_indent()

    count = max(len(lhs.digits), len(rhs.digits))
    for pos in reversed(range(0, count)):  # from smallest to largest component
        log(f'Test digits {lhs[pos]} and {rhs[pos]}...')
        if lhs[pos] > rhs[pos]:
            log(f'{lhs[pos]} > {rhs[pos]} -- {lhs} is NOT less than {rhs}, it is greater than')
            return False
        elif lhs[pos] < rhs[pos]:
            log(f'{lhs[pos]} < {rhs[pos]} -- {lhs} is less than {rhs}')
            return True
        else:
            log(f'{lhs[pos]} == {rhs[pos]} -- continuing testing')

    log(f'No more digits to test -- {lhs} is NOT less than {rhs}, it is equal')
    return False

Greater Than

The algorithm used by humans to test for whole number greater than relies on the idea that numbers represented in place-value notation can be broken down into single digit components -- the place of each digit in the number represents some portion of that number's value. For example, the number 935 can be broken down as 9 100s, 3 10s, and 5 1s...

100
100
100
100
100            1
100            1
100     10     1
100     10     1
100     10     1
---     --     -
900     30     5



9 3 5
│ │ │
│ │ └─ ●
│ │    ● 
│ │    ● 
│ │    ● 
│ │    ● 
│ │
│ └─── ●●●●●●●●●●
│      ●●●●●●●●●●
│      ●●●●●●●●●●
│
└───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
       ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●

Since a number can be broken down into single digit components, each single digit component from the numbers being compared can individually tested from most significant to least significant (left-to-right). If a digit from the number being tested is...

• less than the corresponding digit from the number being tested against, the number being tested is less than (algorithm ends).
• greater than the corresponding digit from the number being tested against, the number being tested is greater than (algorithm ends).
• equal to the corresponding digit from the number being tested against, continue to testing the next digit.

If no more digits are remaining for testing, the number being tested is equal.

For example, imagine testing the number 23 and 21...

2 3                      2 1
│ │                      │ │
│ └─ ●                   │ └─ ●
│    ●                   │
│    ●                   └─── ●●●●●●●●●●
│                             ●●●●●●●●●●
└─── ●●●●●●●●●●
     ●●●●●●●●●●

The first digits are equal (2 == 2), so move to the next digit. The next digit is larger than the other digit (3 > 1), so 23 is greater than than 21.

The way to perform this algorithm via code is as follows...

arithmetic_code/WholeNumber.py (lines 194 to 221):

@log_decorator
def __gt__(lhs: WholeNumber, rhs: WholeNumber) -> bool:
    if isinstance(rhs, int):
        rhs = WholeNumber.from_int(rhs)
    elif isinstance(rhs, str):
        rhs = WholeNumber.from_str(rhs)

    if not isinstance(rhs, WholeNumber):
        raise Exception()

    log(f'Greater than testing {lhs} and {rhs}...')
    log_indent()

    count = max(len(lhs.digits), len(rhs.digits))
    for pos in reversed(range(0, count)):  # from smallest to largest component
        log(f'Test digits {lhs[pos]} and {rhs[pos]}...')
        if lhs[pos] > rhs[pos]:
            log(f'{lhs[pos]} > {rhs[pos]} -- {lhs} is greater than {rhs}')
            return True
        elif lhs[pos] < rhs[pos]:
            log(f'{lhs[pos]} < {rhs[pos]} -- {lhs} is NOT greater than {rhs}, it is less than')
            return False
        else:
            log(f'{lhs[pos]} == {rhs[pos]} -- continuing testing')

    log(f'No more digits to test -- {lhs} is NOT greater than {rhs}, it is equal')
    return False

Addition

The algorithm used by humans to add large whole numbers together is called vertical addition. Vertical addition relies on two ideas...

1. Humans can easily add a single digit number to another single digit number without much effort. For example...

   • 3+4=7
   • 1+9=10
   • 9+9=18

   ... are all addition operations that don't take much effort / are already probably cached in person's memory.

2. Numbers represented in place-value notation can be broken down into single digit components -- the place of each digit in the number represents some portion of that number's value. For example, the number 935 can be broken down as 9 100s, 3 10s, and 5 1s...

   100
   100
   100
   100
   100            1
   100            1
   100     10     1
   100     10     1
   100     10     1
   ---     --     -
   900     30     5
   
   
   
   9 3 5
   │ │ │
   │ │ └─ ●
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │
   │ └─── ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │
   └───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

Since a number can be broken down into single digit components and adding a single digit to any number is easy, any two numbers can be added by adding their individual single digit components. For example, the number 53 and 21 are broken down as follows...

5 3                      2 1
│ │                      │ │
│ └─ ●                   │ └─ ●
│    ●                   │
│    ●                   └─── ●●●●●●●●●●
│                             ●●●●●●●●●●
└─── ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

Add their individual single digit components together to get the sum. The ...

• 1s place combines the 3 items and 1 item together to get 4 items: 3 + 1 results in 4
• 10s place combines the 5 rows and 2 rows together to get 7 rows: 50 + 20 result in 70

7 4
│ │
│ └─ ●
│    ● 
│    ● 
│    ● 
│
└─── ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

In certain cases, the addition of two single digit components may bleed over to the next single digit component. For example, adding 93 and 21 can be broken down as follows...

• 1s place combines the 3 items and 1 item together to get 4 items: 3 + 1 results in 4
• 10s place combines the 9 rows and 2 rows together to get 7 rows: 90 + 20 result in 110

Combining the 10s place resulted in a bleed over to the hundreds place. This extra 100s place bleed over digit can be carried over and combined into the hundreds place. This process is called carry-over -- you're carrying-over the extra bleed over digit to its correct place and combining it with whatever else is there.

Conceptually, carrying-over is the idea of breaking out a group of 10 from the current place and moving them over to the next highest place (e.g. 10s place to 100s place). For example, when adding 93 to 21, adding the digits at the 10's place (90+20) results in 110...

9 3                      2 1
│ │                      │ │
│ └─ ●                   │ └─ ●
│    ●                   │
│    ●                   └─── ●●●●●●●●●●
│                             ●●●●●●●●●●
└─── ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

results in 

11 4
│  │
│  └─ ●
│     ● 
│     ● 
│     ● 
│
└─── ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

Since 11 is too many digits for the tens place (each place must only have 1 digit), break out 10 groups from the 10s place and move those over to the 100s place...

11 4
│  │
│  └─ ●
│     ● 
│     ● 
│     ● 
│
└─── ●●●●●●●●●●
    ┌──────────┐
    │●●●●●●●●●●│
    │●●●●●●●●●●│ each group is 10 items and we grabbed 10 of them (that's 100 items total)
    │●●●●●●●●●●│
    │●●●●●●●●●●│
    │●●●●●●●●●●│
    │●●●●●●●●●●│
    │●●●●●●●●●●│
    │●●●●●●●●●●│
    │●●●●●●●●●●│
    │●●●●●●●●●●│
    └──────────┘

move those 100 items as 1 group of 100s

1 1 4
│ │ │
│ │ └─ ●
│ │    ● 
│ │    ● 
│ │    ● 
│ │
│ └─── ●●●●●●●●●●
│     ┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
└─────│●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●│
      └────────────────────────────────────────────────────────────────────────────────────────────────────┘

The digit in the 10s place is the result for the 10s place, while the digit in the 100s place gets combined in with the 100s place. In the above example, the 100s place was empty, so the carry-over remained as-is.

The way to perform this algorithm in real-life is to stack the two numbers being added on top of each other, where the positions for both numbers match up (e.g. the 1s position matches up, the 10s position matches up, the 100s position matched up, etc..). Then, add the individual single digit components together (from right-to-left). For example...

$\begin{alignedat}{3}{1}& \enspace{5}& \enspace{3}& \{ }& \enspace{2}& \enspace{1}& \enspace + \ \hline{1}& \enspace{7}& \enspace{4}&\end{alignedat}$

If 2 individual single digit components combine together to results in an extra digit (e.g. 5+8=13), the bleed over digit is carried over to the next position (on the left). This is denoted by stacking the bleed over digit on top of the next position -- it's being combined along with the other digits at that position. For example...

$\begin{alignedat}{3}{1}& \enspace{ }& \enspace{ }& \{5}& \enspace{5}& \enspace{1}& \{ }& \enspace{8}& \enspace{1}& \enspace + \ \hline{6}& \enspace{3}& \enspace{2}&\end{alignedat}$

The way to perform this algorithm via code is as follows...

arithmetic_code/WholeNumber.py (lines 227 to 284):

@log_decorator
def __add__(lhs: WholeNumber, rhs: WholeNumber) -> WholeNumber:
    log(f'Adding {lhs} and {rhs}...')
    log_indent()

    cache = [
        [0,  1,  2,  3,  4,  5,  6,  7,  8,  9],
        [1,  2,  3,  4,  5,  6,  7,  8,  9, 10],
        [2,  3,  4,  5,  6,  7,  8,  9, 10, 11],
        [3,  4,  5,  6,  7,  8,  9, 10, 11, 12],
        [4,  5,  6,  7,  8,  9, 10, 11, 12, 13],
        [5,  6,  7,  8,  9, 10, 11, 12, 13, 14],
        [6,  7,  8,  9, 10, 11, 12, 13, 14, 15],
        [7,  8,  9, 10, 11, 12, 13, 14, 15, 16],
        [8,  9, 10, 11, 12, 13, 14, 15, 16, 17],
        [9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
    ]

    count = max(len(lhs.digits), len(rhs.digits))

    carryover_digit = None
    result = WholeNumber.from_int(0)
    for pos in range(0, count):  # from smallest to largest component
        log(f'Targeting {lhs._highlight(pos)} and {rhs._highlight(pos)}')
        log_indent()

        digit1 = lhs[pos]
        digit2 = rhs[pos]

        added = WholeNumber.from_int(cache[digit1.value][digit2.value])
        log(f'Using cache for initial add: {digit1} + {digit2} = {added}')

        if carryover_digit is not None:
            log(f'Using recursion for carryover add: {added} + {carryover_digit} = ...')
            added = added + WholeNumber.from_digit(carryover_digit)  # recurse -- this called __add__()
            carryover_digit = None

        if len(added) == 1:
            result[pos] = added[0]
        elif len(added) == 2:
            result[pos] = added[0]      # keep 1s digit
            carryover_digit = added[1]  # carryover 10s digit
        else:
            raise Exception('This should never happen')

        log(f'Result: {result._highlight(pos)}, Carryover: {carryover_digit}')
        log_unindent()

    if carryover_digit is not None:
        log(f'Remaining carryover: {lhs._highlight(count)}  [{carryover_digit}]')
        result[count] = carryover_digit
        log(f'Result: {result._highlight(count)}')

    log_unindent()
    log(f'Sum: {result}')

    return result

Subtraction

The algorithm used by humans to subtract large whole numbers from each other is called vertical subtraction. Vertical subtraction relies on two ideas...

1. Humans can easily subtract a small 1 to 2 digit numbers (anything smaller than 20) from each other without much effort. For example...

   • 4-3=1
   • 10-1=9
   • 15-3=13

   ... are all subtraction operations that don't take much effort / are already probably cached in person's memory.

2. Numbers represented in place-value notation can be broken down into single digit components -- the place of each digit in the number represents some portion of that number's value. For example, the number 935 can be broken down as 9 100s, 3 10s, and 5 1s...

   100
   100
   100
   100
   100            1
   100            1
   100     10     1
   100     10     1
   100     10     1
   ---     --     -
   900     30     5
   
   
   
   9 3 5
   │ │ │
   │ │ └─ ●
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │
   │ └─── ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │
   └───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

Since a number can be broken down into single digit components and subtracting a single digit to any number is easy, any two numbers can be subtracted by subtracting their individual single digit components. For example, the number 53 and 21 are broken down as follows...

5 3                      2 1
│ │                      │ │
│ └─ ●                   │ └─ ●
│    ●                   │
│    ●                   └─── ●●●●●●●●●●
│                             ●●●●●●●●●●
└─── ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

Subtract their individual single digit components from each other to get the difference. The ...

• 1s place removes 1 item from 3 items to get 2 items: 3 - 1 results in 2
• 10s place removes 2 rows from 5 rows together to get 3 rows: 50 - 20 result in 30

3 2
│ │
│ └─ ●
│    ● 
│
└─── ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

In certain cases, the subtraction of two single digit components may not be possible. For example, subtracting 91 and 23...

9 1                      2 3
│ │                      │ │
│ └─ ●                   │ └─ ●
│                        │    ●
└─── ●●●●●●●●●●          │    ●
     ●●●●●●●●●●          │
     ●●●●●●●●●●          └─── ●●●●●●●●●●
     ●●●●●●●●●●               ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

The ...

• 1s place removes 3 items from 1 item to get ??? items: 1-3 is not possible
• 10s place removes the 2 rows from 9 rows to get 7 rows: 90 - 20 result in 70

The algorithm fails at the 1s place. It's impossible to remove 3 items from 1 item -- the most that can be removed from 1 item is 1 item. The way to handle this is to pick out 1 group from the 10s place and mover it over back to 1s place...

9 1                      2 3
│ │                      │ │
│ └─ ●                   │ └─ ●
│                        │    ●
└─── ●●●●●●●●●●          │    ●
     ●●●●●●●●●●          │
     ●●●●●●●●●●          └─── ●●●●●●●●●●
     ●●●●●●●●●●               ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
    ┌──────────┐
    │●●●●●●●●●●│ each group is 10 items and we grabbed 1 of them (that's 10 items total)
    └──────────┘

move those items back to the 1s place

8 11                     2 3
│ │                      │ │
│ └─ ●                   │ └─ ●
|   ┌─┐                  │    ●
│   │●│                  │    ●
│   │●│                  │
│   │●│                  └─── ●●●●●●●●●●
│   │●│                       ●●●●●●●●●●
│   │●│                  
│   │●│
│   │●│
│   │●│
│   │●│
│   │●│
│   └─┘
│
└─── ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

Now it's possible to subtract. The ...

• 1s place removes 3 items from 11 item to get 8 items: 11-3 results in 8
• 10s place removes the 2 rows from 8 rows to get 6 rows: 80 - 20 result in 60

This process is called borrowing -- you're borrowing 1 group from the next largest position and moving those items back so that there's enough for subtraction to take place. In total, the value is still the same -- the total number of items (dots) doesn't change, but the items are being moved around so that the subtraction of a component can happen.

In certain cases, a group may need to be borrowed but the next largest position is 0. For example, subtracting 100 and 11...

1 0 0                      1 1
│ │ │                      │ │
│ │ └─ ●                   │ └─ ●
│ │                        │
│ └─── <empty>             └─── ●●●●●●●●●●
│
└───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●

Borrow recursively to handle this case:

• subtract 1s position: 0-1 not possible, borrow from 10s position

  • borrow from 10s position: can't borrow 10s position is 0, borrow from 100s position

    • borrow from 100s position: 100s position changes from 1 to 0

      1 0 0                      1 1
      │ │ │                      │ │
      │ │ └─ ●                   │ └─ ●
      │ │                        │
      │ └─── <empty>             └─── ●●●●●●●●●●
      │     ┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
      └─────│●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●│
            └────────────────────────────────────────────────────────────────────────────────────────────────────┘
      
      move those items back to the 10s place (1 group in 100s becomes 10 groups in the 10s)
      
      0 10 0                      1 1
      │ │  │                      │ │
      │ │  └─ ●                   │ └─ ●
      │ │                         │
      │ └───┌──────────┐          └─── ●●●●●●●●●●
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     │●●●●●●●●●●│
      │     └──────────┘
      │
      └───── <empty>
      

  • borrow from 10s position: 10s position changes from 10 to 9

    0 10 0                      1 1
    │ │  │                      │ │
    │ │  └─ ●                   │ └─ ●
    │ │                         │
    │ └─── ●●●●●●●●●●           └─── ●●●●●●●●●●
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │     ┌──────────┐
    |     │●●●●●●●●●●│
    │     └──────────┘
    │
    └───── <empty>
    
        move those items back to the 1s place (1 group in 10s becomes 10 items in the 1s)
    
    0 9 10                     1 1
    │ │ │                      │ │
    │ │ └─┌─┐                  │ └─ ●
    │ │   │●│                  │
    │ │   │●│                  └─── ●●●●●●●●●●
    │ │   │●│
    │ │   │●│
    │ │   │●│
    │ │   │●│
    │ │   │●│
    │ │   │●│
    │ │   │●│
    │ │   │●│
    │ │   └─┘
    │ └─── ●●●●●●●●●●          
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●● 
    │      ●●●●●●●●●●
    │
    └───── <empty>
    

• subtract 1s position: 10-1 results in 9

• subtract 10s position: 9-1 results in 8

• subtract 100s position: 0-0 results in 0 (why? because 11 is the same as 011)

The way to perform this algorithm in real-life is to stack the two numbers being subtracted on top of each other, where the positions for both numbers match up (e.g. the 1s position matches up, the 10s position matches up, the 100s position matched up, etc..). Then, subtract the individual single digit components together (from right-to-left). Every time borrowing is needed, cross out the number being changed and put the place their new numbers above. For example, subtracting 100 and 11 ...

$\begin{alignedat}{3}{1}& \enspace{0}& \enspace{0}& \{ }& \enspace{1}& \enspace{1}& \enspace - \ \hline{ }& \enspace{ }& \enspace{ }&\end{alignedat}$

• subtract 1s position: 0-1 not possible, borrow from 10s position

  • borrow from 10s position: can't borrow 10s position is 0, borrow from 100s position

    • borrow from 100s position: 100s position subtracts 1 (goes from 1 to 0), 10s position adds 10 (goes from 0 to 10)

      $\begin{alignedat}{3}{0}& \enspace{10}& \enspace{ }& \\cancel{1}& \enspace\cancel{ 0}& \enspace{0}& \{ }& \enspace{ 1}& \enspace{1}& \enspace - \ \hline{ }& \enspace{ }& \enspace{ }&\end{alignedat}$

  • borrow from 10s position: 10s subtracts 1 (goes from 10 to 9), 1s position adds 10 (goes from 0 to 10)

    $\begin{alignedat}{3}{ }& \enspace{ 9}& \enspace{ }& \{0}& \enspace\cancel{10}& \enspace{10}& \\cancel{1}& \enspace\cancel{ 0}& \enspace\cancel{ 0}& \{ }& \enspace{ 1}& \enspace{ 1}& \enspace - \ \hline{ }& \enspace{ }& \enspace{ }&\end{alignedat}$

• subtract 1s position: 10-1 results in 9

  $\begin{alignedat}{3}{ }& \enspace{ 9}& \enspace{ }& \{0}& \enspace\cancel{10}& \enspace{10}& \\cancel{1}& \enspace\cancel{ 0}& \enspace\cancel{ 0}& \{ }& \enspace{ 1}& \enspace{ 1}& \enspace - \ \hline{ }& \enspace{ }& \enspace{ 9}&\end{alignedat}$

• subtract 10s position: 9-1 results in 8

  $\begin{alignedat}{3}{ }& \enspace{ 9}& \enspace{ }& \{0}& \enspace\cancel{10}& \enspace{10}& \\cancel{1}& \enspace\cancel{ 0}& \enspace\cancel{ 0}& \{ }& \enspace{ 1}& \enspace{ 1}& \enspace - \ \hline{ }& \enspace{ 8}& \enspace{ 9}&\end{alignedat}$

• subtract 100s position: 0-0 results in 0

  $\begin{alignedat}{3}{ }& \enspace{ 9}& \enspace{ }& \{0}& \enspace\cancel{10}& \enspace{10}& \\cancel{1}& \enspace\cancel{ 0}& \enspace\cancel{ 0}& \{ }& \enspace{ 1}& \enspace{ 1}& \enspace - \ \hline{0}& \enspace{ 8}& \enspace{ 9}&\end{alignedat}$

  ⚠️NOTE️️️⚠️

  The number 11 has nothing in its 100s place -- nothing is the same as 0. 11 is the same as 011.

The way to perform this algorithm via code is as follows...

arithmetic_code/WholeNumber.py (lines 287 to 374):

@log_decorator
def __sub__(lhs: WholeNumber, rhs: WholeNumber) -> WholeNumber:
    log(f'Subtracting {lhs} and {rhs}...')
    log_indent()

    sub_cache = [
        [0,    None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None],
        [1,    0,    None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None],
        [2,    1,    0,    None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None],
        [3,    2,    1,    0,    None, None, None, None, None, None, None, None, None, None, None, None, None, None, None, None],
        [4,    3,    2,    1,    0,    None, None, None, None, None, None, None, None, None, None, None, None, None, None, None],
        [5,    4,    3,    2,    1,    0,    None, None, None, None, None, None, None, None, None, None, None, None, None, None],
        [6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None, None, None, None, None, None, None, None, None],
        [7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None, None, None, None, None, None, None, None],
        [8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None, None, None, None, None, None, None],
        [9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None, None, None, None, None, None],
        [10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None, None, None, None, None],
        [11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None, None, None, None],
        [12,   11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None, None, None],
        [13,   12,   11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None, None],
        [14,   13,   12,   11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None, None],
        [15,   14,   13,   12,   11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None, None],
        [16,   15,   14,   13,   12,   11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None, None],
        [17,   16,   15,   14,   13,   12,   11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None, None],
        [18,   17,   16,   15,   14,   13,   12,   11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0,    None],
        [19,   18,   17,   16,   15,   14,   13,   12,   11,   10,   9,    8,    7,    6,    5,    4,    3,    2,    1,    0   ]
    ]

    # copy self because it may get modified during borrowing phase
    self_copy = lhs.copy()

    count = max(len(self_copy.digits), len(rhs.digits))

    result = WholeNumber.from_int(0)
    for pos in range(0, count):  # from smallest to largest component
        log(f'Targeting {self_copy._highlight(pos)} and {rhs._highlight(pos)}')
        log_indent()

        digit1 = self_copy[pos]
        digit2 = rhs[pos]
        result_digit = sub_cache[digit1.value][digit2.value]
        if result_digit is not None:
            log(f'Using cache for subtraction: {digit1} - {digit2} = {result_digit}')
        else:
            log('Not possible -- attempting to borrow')
            self_copy._borrow_from_next(sub_cache, pos)

            digit1 = self_copy[pos]
            digit2 = rhs[pos]
            result_digit = sub_cache[digit1.value][digit2.value]
            log(f'Using cache for subtraction: {digit1} - {digit2} = {result_digit}')

        result[pos] = result_digit
        log(f'Result: {result._highlight(pos)}')
        log_unindent()

    log_unindent()
    log(f'Difference: {result}')

    return result

@log_decorator
def _borrow_from_next(self: WholeNumber, sub_cache: List[List[int]], pos: int) -> None:
    if pos >= len(self):
        raise Exception('Not enough available to borrow')

    curr_digit = self[pos]
    next_digit = self[pos + 1]

    log(f'Borrowing from next largest {self._highlight(pos + 1)}')

    if next_digit == 0:
        log(f'Not possible -- attempting to borrow again')
        self._borrow_from_next(sub_cache, pos + 1)  # recursively borrow
        next_digit = self[pos + 1]  # updated because of borrow call above

    next_digit = sub_cache[next_digit.value][1]                             # sub 1 from next largest position
    curr_digit = (WholeNumber.from_int(10) + WholeNumber.from_digit(curr_digit))._as_digit()    # add 10 to current position

    # curr_digit is no longer an actual digit -- it's beyond the value of 9 (a digit is 0..9). We're using a
    # hack to get a out-of-bounds value as a digit because we need to subtract from it later on -- this is
    # trying to faithfully replicate the 'borrowing' logic in vertical subtraction

    self[pos + 1] = next_digit
    self[pos] = curr_digit

    log(f'Completed borrowing {self._highlight(pos, pos + 1)}')

Multiplication

The algorithm used by humans to multiply large whole numbers together is called vertical multiplication. Vertical multiplication relies on three ideas...

1. Humans have the ability to multiply a single digit number to another single digit number through memorization. For example...

   • 3*4=12 (3+3+3+3)
   • 1*9=9 (9)
   • 9*9=81 (9+9+9+9+9+9+9+9+9)

   ... are all multiplication operations that can be done quickly if the person has cached the table below into their memory.

   *	0	1	2	3	4	5	6	7	8	9
   0	0	0	0	0	0	0	0	0	0	0
   1	0	1	2	3	4	5	6	7	8	9
   2	0	2	4	6	8	10	12	14	16	18
   3	0	3	6	9	12	15	18	21	24	27
   4	0	4	8	12	15	20	24	28	32	36
   5	0	5	10	15	20	25	30	35	40	45
   6	0	6	12	18	24	30	36	42	48	54
   7	0	7	14	21	28	35	42	49	56	63
   8	0	8	16	24	32	40	48	56	64	72
   9	0	9	18	27	36	45	54	63	72	81

2. Numbers represented in place-value notation can be broken down into single digit components -- the place of each digit in the number represents some portion of that number's value. For example, the number 935 can be broken down as 9 100s, 3 10s, and 5 1s...

   100
   100
   100
   100
   100            1
   100            1
   100     10     1
   100     10     1
   100     10     1
   ---     --     -
   900     30     5
   
   
   
   9 3 5
   │ │ │
   │ │ └─ ●
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │
   │ └─── ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │
   └───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

3. If two numbers start with a single non-zero digit is followed by zero or more 0s, the result of their multiplication is equivalent to multiplying the single non-zero digits together and appending the 0s to the end. For example, ..

   • 30 * 2 = 60 -- 3 ends in 1 zero and 2 ends in no zeros, so the result has 1 zero

     ┌─┬─┬─┐
     │●│●│●│
     ├─┼─┼─┤  3*2, each box has 1 item and there's 6 boxes -- 6 total items
     │●│●│●│       
     └─┴─┴─┘
     
     ┌──────────┬──────────┬──────────┐
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     ├──────────┼──────────┼──────────┤ 30*2, each box has 10 items and there's 6 boxes -- 60 total items
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│       
     └──────────┴──────────┴──────────┘
     

   • 3 * 20 = 60 -- 3 ends in no zeros and 2 ends in 1 zero, so the result has 1 zero

     ┌─┬─┬─┐
     │●│●│●│
     ├─┼─┼─┤  3*2, each box has 1 item and there's 6 boxes -- 6 total items
     │●│●│●│       
     └─┴─┴─┘
     
     ┌─┬─┬─┐
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     ├─┼─┼─┤ 3 * 20, each box has 10 items and there's 6 boxes -- 60 total items
     │●│●│●│         
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     │●│●│●│
     └─┴─┴─┘
     

   • 30 * 20 = 600 -- 30 ends in 1 zero and 20 ends in 1 zero, so the result has 2 zeros

     ┌─┬─┬─┐
     │●│●│●│
     ├─┼─┼─┤  3*2, each box has 1 item and there's 6 boxes -- 6 total items
     │●│●│●│       
     └─┴─┴─┘
     
     ┌──────────┬──────────┬──────────┐
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     ├──────────┼──────────┼──────────┤ 30 * 20, box has 100 items and there's 6 boxes -- 600 total items
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│           
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     │●●●●●●●●●●│●●●●●●●●●●│●●●●●●●●●●│
     └──────────┴──────────┴──────────┘
     

Any two numbers can be multiplied by ...

1. breaking down each number into its single digit components (idea 2 above),
2. then multiplying each component from the first number by each components from the second number (idea 1 and 3 above),
3. then adding the results of those multiplications.

For example, the number 43 and 2 are broken down as follows...

4 3                      2
│ │                      │
│ └─ ●                   └─ ●
│    ●                      ●         
│    ●               
│                        
└─── ●●●●●●●●●●          
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

• 43 is 40 + 3 (4 in the 10s place / 3 in the 1s place)
• 2 is 2 (2 in the 1s place)

Multiply their individual single digit components together results in ...

• 2*3 results in 6 (see idea 1)
• 2*40 results in 80, because 2*4 is 8 (see idea 1) and the zeros from numbers multiplied are appended to the result (see idea 3)

Add the results of the multiplications: 80 + 6 is 86. Note that 43 + 43 is also 86. Each multiplication above is giving back a portion of the final multiplication value, specifically a portion of a single digit component in the final multiplication value -- they need to be combined by adding.

8 6
│ │ ┌─┐
│ └─┤●│
│   │●│ 3        
│   │●│
│   ├─┤
│   │●│
│   │●│ 3
│   │●│
│   └─┘
│   ┌──────────┐
└───┤●●●●●●●●●●│          
    │●●●●●●●●●●│
    │●●●●●●●●●●│ 4
    │●●●●●●●●●●│
    ├──────────┤
    │●●●●●●●●●●│
    │●●●●●●●●●●│
    │●●●●●●●●●●│ 4
    │●●●●●●●●●●│
    └──────────┘

For another more complex example, the number 43 and 22 are broken down as follows...

4 3                      2 2
│ │                      │ │
│ └─ ●                   │ └─ ●
│    ●                   │    ●         
│    ●                   │              
│                        └─── ●●●●●●●●●●
└─── ●●●●●●●●●●               ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●
     ●●●●●●●●●●

• 43 is 40 + 3 (4 in the 10s place / 3 in the 1s place)
• 22 is 20 + 2 (2 in the 10s place / 2 in the 1s place)

Multiply their individual single digit components together results in ...

• 2*3 results in 6 (see idea 1)
• 2*40 results in 80, because 2*4 is 8 (see idea 1) and the zeros from numbers multiplied are appended to the result (see idea 3)
• 20*3 results in 60, because 2*3 is 6 (see idea 1) and the zeros from numbers multiplied are appended to the result (see idea 3)
• 20*40 results in 800, because 2*4 is 8 (see idea 1) and the zeros from numbers multiplied are appended to the result (see idea 3)

Add the results of the multiplications: 800 + 60 + 80 + 6 is 946. Note that 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 + 43 is also 946. Each multiplication above is giving back a portion of the final multiplication value, specifically a portion of a single digit component in the final multiplication value -- they need to be combined by adding.

The way to perform this algorithm in real-life is to stack the two numbers being multiplied on top of each other, where the positions for both numbers match up (e.g. the 1s position matches up, the 10s position matches up, the 100s position matched up, etc..). For example...

$\begin{alignedat}{3}{ }& \enspace{4}& \enspace{3}& \{ }& \enspace{2}& \enspace{2}& \enspace * \ \hline{ }& \enspace{ }& \enspace{ }&\end{alignedat}$

Then, for each component in the bottom number (from right-to-left), isolate to its single digit component and multiply by each component in the top number (from right-to-left). The answer for each digit of the bottom row is written underneath the answer prior to it. Starting from the first component of the bottom number...

• Isolate to 2 (bottom) and 3 (top), resulting in 6.

  $\begin{alignedat}{3}{ }& \enspace{4}& \enspace{\green{3}}& \{ }& \enspace{2}& \enspace{\green{2}}& \enspace * \ \hline{ }& \enspace{ }& \enspace{\green{6}}&\end{alignedat}$

• Isolate to 2 (bottom) and 40 (top), resulting in 80. Only the 8 needs to be written because this is effectively the same as doing 40*2 (80) then adding the 6 from the 3*2 prior -- 80+6 is 86.

  $\begin{alignedat}{3}{ }& \enspace{\green{4}}& \enspace{3}& \{ }& \enspace{2}& \enspace{\green{2}}& \enspace * \ \hline{ }& \enspace{\green{8}}& \enspace{6}&\end{alignedat}$

• Isolate to 20 (bottom) and 3 (top), resulting in 60.

  $\begin{alignedat}{3}{ }& \enspace{4}& \enspace{\green{3}}& \{ }& \enspace{\green{2}}& \enspace{2}& \enspace * \ \hline{ }& \enspace{8}& \enspace{6}& \{ }& \enspace{\green{6}}& \enspace{\green{0}}&\end{alignedat}$

• Isolate to 20 (bottom) and 40 (top), resulting in 800. Only the 8 needs to be written because this is effectively the same as doing 40*20 (800) then adding the 60 from the 3*20 prior -- 800+60 is 860.

  $\begin{alignedat}{3}{ }& \enspace{\green{4}}& \enspace{3}& \{ }& \enspace{\green{2}}& \enspace{2}& \enspace * \ \hline{ }& \enspace{8}& \enspace{6}& \{\green{8}}& \enspace{6}& \enspace{0}&\end{alignedat}$

Then, add the answers from each bottom iteration to get the final answer...

$\begin{alignedat}{3}{ }& \enspace{4}& \enspace{3}& \{ }& \enspace{2}& \enspace{2}& \enspace * \ \hline{ }& \enspace{8}& \enspace{6}& \{8}& \enspace{6}& \enspace{0}& \enspace + \ \hline{\green{9}}& \enspace{\green{4}}& \enspace{\green{6}}&\end{alignedat}$

In many cases, multiplying 2 individual single digit components results in an extra digit (e.g. 7*7=49). If this happens, the bleed over digit is carried over to the next position (on the left). That is, the bleed over digit will get added to the result of the multiplication in the next position. This is denoted by stacking the bleed over digit on top of the next position. For example...

$\begin{alignedat}{3}{ }& \enspace{7}& \enspace{7}& \{ }& \enspace{7}& \enspace{7}& \enspace * \ \hline{ }& \enspace{ }& \enspace{ }&\end{alignedat}$

• Isolate to 7 (bottom) and 7 (top), resulting in 49. The 9 is kept and 40 carries over to the next position.

  $\begin{alignedat}{3}{ }& \enspace{\green{4}}& \enspace{ }& \{ }& \enspace{7}& \enspace{\green{7}}& \{ }& \enspace{8}& \enspace{\green{7}}& \enspace * \ \hline{ }& \enspace{ }& \enspace{\green{9}}&\end{alignedat}$

• Isolate to 7 (bottom) and 70 (top), resulting in 490. Add the 40 from the carry-over to make it 530. Only the 53 needs to be written because this is effectively the same as having 530 then adding the 9 from the 7*7 prior -- 530+9 is 539.

  $\begin{alignedat}{3}{ }& \enspace{\green{4}}& \enspace{ }& \{ }& \enspace{\green{7}}& \enspace{7}& \{ }& \enspace{8}& \enspace{\green{7}}& \enspace * \ \hline{\green{5}}& \enspace{\green{3}}& \enspace{9}&\end{alignedat}$

• Isolate to 80 (bottom) and 7 (top), resulting in 560. The 60 is kept and 500 carries over to the next position.

  $\begin{alignedat}{3}{ }& \enspace{\green{5}}& \enspace{ }& \{ }& \enspace{4}& \enspace{ }& \{ }& \enspace{7}& \enspace{\green{7}}& \{ }& \enspace{\green{8}}& \enspace{7}& \enspace * \ \hline{5}& \enspace{3}& \enspace{9}& \{ }& \enspace{\green{6}}& \enspace{\green{0}}&\end{alignedat}$

• Isolate to 80 (bottom) and 70 (top), resulting in 5600. Add the 500 from the carry-over to make it 6100. Only the 61 needs to be written because this is effectively the same as having 6100 then adding the 60 from the 80*7 prior -- 6100+60 is 6160.

  $\begin{alignedat}{4}{ }& \enspace{ }& \enspace{\green{5}}& \enspace{ }& \{ }& \enspace{ }& \enspace{4}& \enspace{ }& \{ }& \enspace{ }& \enspace{\green{7}}& \enspace{7}& \{ }& \enspace{ }& \enspace{\green{8}}& \enspace{7}& \enspace * \ \hline{ }& \enspace{5}& \enspace{3}& \enspace{9}& \{\green{6}}& \enspace{\green{1}}& \enspace{6}& \enspace{0}&\end{alignedat}$

Then, add the answers from each bottom iteration to get the final answer...

$\begin{alignedat}{4}{ }& \enspace{ }& \enspace{5}& \enspace{ }& \{ }& \enspace{ }& \enspace{4}& \enspace{ }& \{ }& \enspace{ }& \enspace{7}& \enspace{7}& \{ }& \enspace{ }& \enspace{8}& \enspace{7}& \enspace * \ \hline{ }& \enspace{5}& \enspace{3}& \enspace{9}& \{\green{6}}& \enspace{\green{1}}& \enspace{6}& \enspace{0}& \enspace + \ \hline{\green{6}}& \enspace{\green{6}}& \enspace{\green{9}}& \enspace{\green{9}}&\end{alignedat}$

The way to perform this algorithm via code is as follows...

arithmetic_code/WholeNumber.py (lines 377 to 462):

@log_decorator
def __mul__(lhs: WholeNumber, rhs: WholeNumber) -> WholeNumber:
    log(f'Multiplying {lhs} and {rhs}...')
    log_indent()

    count = len(rhs.digits)

    res_list = []
    for pos in range(0, count):  # from smallest to largest component
        log(f'Targeting {lhs} and {rhs._highlight(pos)}')
        log_indent()

        self_copy = lhs.copy()    # create a copy
        self_copy.shift_left(pos)  # shift copy (add 0s) based on the digit we're on
        log(f'Appending 0s to multiplicand based on position of multiplier (pos {pos}): {self_copy} {rhs._highlight(pos)}')

        res = self_copy._single_digit_mul(rhs[pos])  # multiply copy by that digit
        log_unindent()

        res_list.append(res)

    log(f'Summing intermediate results to get final result...')
    log_indent()
    final_res = WholeNumber.from_int(0)
    for res in res_list:
        log(f'Adding {res} to {final_res}')
        final_res += res
    log_unindent()

    log_unindent()
    log(f'Product: {final_res}')

    return final_res

@log_decorator
def _single_digit_mul(self: WholeNumber, digit: Digit) -> WholeNumber:
    cache = [
        [0,  0,  0,  0,  0,  0,  0,  0,  0,  0 ],
        [0,  1,  2,  3,  4,  5,  6,  7,  8,  9 ],
        [0,  2,  4,  6,  8,  10, 12, 14, 16, 18],
        [0,  3,  6,  9,  12, 15, 18, 21, 24, 27],
        [0,  4,  8,  12, 16, 20, 24, 28, 32, 36],
        [0,  5,  10, 15, 20, 25, 30, 35, 40, 45],
        [0,  6,  12, 18, 24, 30, 36, 42, 48, 54],
        [0,  7,  14, 21, 28, 35, 42, 49, 56, 63],
        [0,  8,  16, 24, 32, 40, 48, 56, 64, 72],
        [0,  9,  18, 27, 36, 45, 54, 63, 72, 81]
    ]

    count = len(self.digits)

    carryover_digit = None
    result = WholeNumber.from_int(0)
    for pos in range(0, count):  # from smallest to largest component
        log(f'Targeting {self._highlight(pos)} and {digit}')
        log_indent()

        digit1 = self[pos]

        multed = WholeNumber.from_int(cache[digit1.value][digit.value])
        log(f'Using cache for initial mul: {digit1} * {digit} = {multed}')

        if carryover_digit is not None:
            adjusted_multed = multed + WholeNumber.from_digit(carryover_digit)
            log(f'Adding carryover: {multed} + {carryover_digit} = {adjusted_multed}')
            carryover_digit = None
            multed = adjusted_multed

        if len(multed) == 1:
            result[pos] = multed[0]
        elif len(multed) == 2:
            result[pos] = multed[0]      # keep 1s digit
            carryover_digit = multed[1]  # carryover 10s digit
        else:
            raise Exception('This should never happen')

        log(f'Result: {result._highlight(pos)}, Carryover: {carryover_digit}')
        log_unindent()

    if carryover_digit is not None:
        log(f'Remaining carryover: {self._highlight(count)}  [{carryover_digit}]')
        result[count] = carryover_digit
        log(f'Result: {result._highlight(count)}')

    return result

Division

There are 2 algorithms used to divide large whole numbers:

• trial-and-error division
• long division (requires trial-and-error division)

These algorithms are detailed in the subsections below.

Trial and Error

Trial-and-error division is an algorithm used for dividing numbers. The core idea behind the algorithm is that multiplication is the inverse of division. That is, multiplication reverses / un-does division (and vice-versa). For example...

• 3 * 4 = 12 -- If you have 3 groups of 4 items each, you'll have 12 items.
• 12 / 3 = 4 -- If you have 12 items and you break them up into 3 groups, you'll have 4 items in each group.

Knowing this, multiplication can be used to check if some number is the quotient. For example, to find the quotient for 20 / 5...

• 5 * 0 = 0 <-- test 0, no
• 5 * 1 = 5 <-- test 1, no
• 5 * 2 = 10 <-- test 2, no
• 5 * 3 = 15 <-- test 3, no
• 5 * 4 = 20 <-- test 4, FOUND -- 20 / 5 = 4

5 * 4 = 20 -- If you have 5 groups of 4 items each, you'll have 20 items.

Rather than testing each number incrementally, it's faster to start with a large test number and tweak its digits until the multiplication test passes. The algorithm maintains a pointer to a position in the test number which it uses to increment / decrement the digit at that position. Given a test number:

• Starting from the most significant digit, if the product is ...
  • too large then decrement that position until it becomes too small.
  • too small then increment that position until it becomes too large.
  • a match then stop.
• Move to the next significant digit, if the product is ...
  • too large then decrement that position until it becomes too small.
  • too small then increment that position until it becomes too large.
  • a match then stop.
• Move to the next significant digit, if the product is ...
  • too large then decrement that position until it becomes too small.
  • too small then increment that position until it becomes too large.
  • a match then stop.
• ...

It continually does this until either the product matches the correct number or there are no more digits to tweak.

The core ideas behind this algorithm are:

1. When comparing two test numbers, multiplying by the larger test number will result in a larger product.

   • 5 * 100 = 500
   • 5 * 99 = 495
   • 5 * 98 = 490

2. When comparing two test numbers, multiplying by the test number with more digits will result in a larger product.

   • 5 * 100 = 500 (3 digits)
   • 5 * 99 = 495 (2 digits)
   • 5 * 98 = 490 (2 digits)
   • ...

For example, 2617 / 52...

Starting with a test number of 100...

• 100
  • 52 * 100 = 5200 (5200 > 2617, too large - subtract 100)
  • 52 * 000 = 0 (0 < 2617, too small - move to next index)
• 000
  • 52 * 000 = 0 (0 < 2617, too small - add 10)
  • 52 * 010 = 520 (520 < 2617, too small - add 10)
  • 52 * 020 = 1040 (1040 < 2617, too small - add 10)
  • 52 * 030 = 1560 (1560 < 2617, too small - add 10)
  • 52 * 040 = 2080 (2080 < 2617, too small - add 10)
  • 52 * 050 = 2600 (2600 < 2617, too small - add 10)
  • 52 * 060 = 3120 (3120 > 2617, too large - move to next index)
• 060
  • 52 * 060 = 3120 (3120 > 2617, too large - subtract 1)
  • 52 * 059 = 3068 (3068 > 2617, too large - subtract 1)
  • 52 * 058 = 3016 (3016 > 2617, too large - subtract 1)
  • 52 * 057 = 2964 (2964 > 2617, too large - subtract 1)
  • 52 * 056 = 2912 (2912 > 2617, too large - subtract 1)
  • 52 * 055 = 2860 (2860 > 2617, too large - subtract 1)
  • 52 * 054 = 2808 (2808 > 2617, too large - subtract 1)
  • 52 * 053 = 2756 (2756 > 2617, too large - subtract 1)
  • 52 * 052 = 2704 (2704 > 2617, too large - subtract 1)
  • 52 * 051 = 2652 (2652 > 2617, too large - subtract 1)
  • 52 * 050 = 2600 (2600 < 2617, too small - stop because no more digits)

Since there are no more digits left, the quotient is 50 and the remainder is 17 (2617 - 2600 = 17).

In the example above, the starting test number of 100 was selected by taking advantage of a special property of whole number multiplication: the total number of digits in both inputs will equal to either ...

• the number of digits in the product (condition1 below),
• or the number of digits in the product plus 1 (condition2 below).

in1_len = len(input1.digits)
in2_len = len(input2.digits)
product_len = len(product.digits)

condition1 = in1_len + in2_len == product_len
condition2 = in1_len + in2_len == product_len + 1
assert condition1 or condition2

For example, ...

Given this property, the algorithm works backwards to calculate the maximum number of digits that input2's (the unknown input) whole part can be...

min_in2_len = product_len - in1_len
max_in2_len = product_len + 1 - in1_len

For example, ...

The algorithm uses the maximum to pick a starting number: 1 followed by 0s...

In the main example above (52 * ? = 2617), the product has 4 digits and the known input has 2 digits, so a starting test number should of 3 digits was selected: 100.

The trial-and-error division algorithm written as code is as follows:

arithmetic_code/WholeNumber.py (lines 511 to 633):

@staticmethod
@log_decorator
def choose_start_test_num_for_divte(input1: WholeNumber, expected_product: WholeNumber) -> WholeNumber:
    log(f'Choosing a starting test number to find {input1} \\* ? = {expected_product}...')
    log_indent()

    log(f'{input1} has {len(input1.digits)} digits')
    log(f'{expected_product}\'s has {len(expected_product.digits)} digits')
    num_of_zeros = len(expected_product.digits) - len(input1.digits)
    start_test_num = WholeNumber.from_str('1' + '0' * num_of_zeros)

    log(f'Starting test number: {start_test_num}')

    log_unindent()
    log(f'{start_test_num}')
    return start_test_num

@staticmethod
@log_decorator
def choose_start_modifier_for_divte(start_test_num: WholeNumber) -> WholeNumber:
    log(f'Choosing a starting modifier for {start_test_num}...')
    log_indent()

    log(f'{start_test_num} has {len(start_test_num.digits)} digits')
    num_of_zeros = len(start_test_num.digits) - 1
    start_modifier_num = WholeNumber.from_str('1' + '0' * num_of_zeros)

    log(f'Starting modifier: {start_modifier_num}')

    log_unindent()
    log(f'{start_modifier_num}')
    return start_modifier_num

@staticmethod
@log_decorator
def trial_and_error_div(dividend: WholeNumber, divisor: WholeNumber) -> (WholeNumber, WholeNumber):
    if divisor == WholeNumber.from_str('0'):
        raise Exception('Cannot divide by 0')

    log(f'Dividing {dividend} and {divisor}...')
    log_indent()

    log(f'Calculating starting test number...')
    test = WholeNumber.choose_start_test_num_for_divte(divisor, dividend)
    log(f'{test}')

    log(f'Calculating starting modifier for test number...')
    modifier = WholeNumber.choose_start_modifier_for_divte(test)
    log(f'{modifier}')

    class StepType(Enum):
        INCREMENTING = 0
        DECREMENTING = 1
        EQUAL = 2

    last_steptype = None
    while True:
        log(f'Testing {test}: {test} * {divisor}...')
        test_res = test * divisor
        log(f'{test_res}')

        log(f'Is {test_res} ==, >, or < to {dividend}? ...')
        log_indent()
        try:
            if test_res == dividend:
                last_steptype = StepType.EQUAL
                log(f'{test_res} == {dividend} -- Found')
                break
            elif test_res > dividend:
                last_steptype = StepType.DECREMENTING
                log(f'{test_res} > {dividend} -- Decrementing {test} by {modifier} until not >...')
                log_indent()
                while True:
                    log(f'Decrementing {test} by {modifier}...')
                    test -= modifier
                    log(f'{test} * {divisor}...')
                    modify_res = test * divisor
                    log(f'{modify_res}')
                    if not modify_res > dividend:
                        break
                log_unindent()
                log(f'Done: {test}')
            elif test_res < dividend:
                last_steptype = StepType.INCREMENTING
                log(f'{test_res} < {dividend} -- Incrementing {test} by {modifier} until not <...')
                log_indent()
                while True:
                    log(f'Incrementing {test} by {modifier}...')
                    test += modifier
                    log(f'{test} * {divisor}...')
                    modify_res = test * divisor
                    log(f'{modify_res}')
                    if not modify_res < dividend:
                        break
                log_unindent()
                log(f'Done: {test}')
        finally:
            log_unindent()

        if modifier == WholeNumber.from_str('1'):
            break

        log(f'Reducing modifier for next set of tests...')
        modifier = WholeNumber.from_str(str(modifier)[0:-1])
        log(f'{modifier}')

    # if the last set of tests were incrementing, the test number will be 1 more than where it needs to be moved
    # because the loop increments until it exceeds PAST the dividend
    if StepType.INCREMENTING == last_steptype:
        log(f'Decrementing test number (only happens if last set of tests were incrementing)...')
        if test * divisor > dividend:
            test -= WholeNumber.from_str('1')
        log(f'{test}')

    log (f'Determining remainder...')
    remainder = dividend - (test * divisor)
    log(f'{remainder}')

    log_unindent()
    log(f'Quotient: {test}, Remainder: {remainder}')

    return test, remainder

Long Division

The algorithm used by humans to divide large whole numbers is called long division. In most cases, it can divide a number in less steps than trial-and-error division. Long division relies on three ideas...

1. Numbers represented in place-value notation can be broken down into single digit components -- the place of each digit in the number represents some portion of that number's value. For example, the number 935 can be broken down as 9 100s, 3 10s, and 5 1s...

   100
   100
   100
   100
   100            1
   100            1
   100     10     1
   100     10     1
   100     10     1
   ---     --     -
   900     30     5
   
   
   
   9 3 5
   │ │ │
   │ │ └─ ●
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │    ● 
   │ │
   │ └─── ●●●●●●●●●●
   │      ●●●●●●●●●●
   │      ●●●●●●●●●●
   │
   └───── ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
          ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
   

2. Any number can be divided using trial-and-error division. For example, 20 / 5...

   

   • 5 * 1 = 5 <-- test 1, no
   • 5 * 9 = 45 <-- test 9, no
   • 5 * 2 = 10 <-- test 2, no
   • 5 * 8 = 40 <-- test 8, no
   • 5 * 3 = 15 <-- test 3, no
   • 5 * 7 = 35 <-- test 7, no
   • 5 * 4 = 20 <-- test 4, FOUND -- 20 / 5 = 4

3. When dividing, if the number being divided (dividend) has trailing zeros, those trailing zeros can be removed prior to the division and then put back on after the division. For example, 4500 / 6...

   

   When 4500 items are broken up into groups of 6, this rule says that there will be at least 700 groups. 300 of the 4500 items remain unaccounted for, but the rule can be used again on these 300 items because 300 has trailing 0s (recursive).

   ⚠️NOTE️️️⚠️

   It's easy to test if this is correct...

   • 700 * 6 = 4200 (multiply by the quotient)
   • 4200 + 300 = 4500 (add the remainder)

   ⚠️NOTE️️️⚠️

   The reasoning behind why trailing 0s can be removed and re-appended has to do with expressions / order of operations / factoring. Taking the original 4500 / 7 example above...

   • 4500 / 7
   • (45 * 100) / 7 <-- factor out 100 from the 4500
   • 45 * 100 / 7 <-- remove parenthesis, associativity law, mult and div have same precedence so it doesn't matter which gets performed first
   • 45 / 7 * 100 <-- swap, commutative law, mult and div have same precedence so it doesn't matter which gets performed first
   • (45 / 7) * 100
   • (7R3) * 100
   • 700R300

   In certain cases, the quotient returned by the operation will end up being 0. This means that the operation failed.

   If this happens, less trialing-zeros need to be stripped-off. Keep leaving in trialing 0s and re-doing the operation until the quotient becomes non-zero. For example, when all 3 trailing 0s are stripped from 4000 / 6...

   

   ... the quotient is 0 and the remainder is 4000. The operation pretty much failed because the amount of remaining items is the same as the amount starting amount -- nothing was grouped and everything remains. As such, more trialing 0s need to be left in. Re-try the operation with only 2 trialing 0s removed...

   

   ... the quotient is 600 and the remainder is 400. When 4000 items are broken up into groups of 6, there will be at least 600 groups. 400 of the 4000 items remain unaccounted for, but the rule can be used again on these 400 items because 400 has trailing 0s (recursive).

The idea behind long division is to break up the dividend into its individual single digit components results (idea 1) and divide each component by the divisor. For example, 752 / 3...

Each of the divisions are easy to perform because trialing 0s can be stripped-off prior to trial-and-error division (ideas 2 and 3). That is, the actual numbers being input into trial-and-error division are much smaller than they would normally be because trailing 0s are removed. Smaller numbers mean easier to perform.

The remainders need to be accounted for. That is, if there are enough remaining items to form a group, they should be grouped. The process is repeated on the remaining items until there aren't enough to form a group (until the remainder is less than the divisor). Once there aren't enough remaining items to form a group, the sum of the quotients becomes the final quotient (final number of groups) and the remainder becomes the final remainder...

The answer to 752 / 3 is 250R2.

This process can be made much simpler by focusing on one component at a time. Starting from the largest component to the smallest component, divide (using idea 3) but then roll-in (add) the remainder into the next component. The thought process is exactly the same as above -- the division is being performed on a component and the remaining items from that division are being accounted for because they're being added to the next component (which gets divided next). For example, 752 / 3...

1. Divide the largest component (700)...

   

2. Roll in remainder to the second largest component (50) and divide...

   

3. Roll in remainder to the third largest component (2) and divide...

   

4. The sum of the quotients becomes the final quotient, and the last remainder becomes the final remainder...

   

This is effectively the algorithm that humans use for long division -- for each component, divide (using idea 3) and roll in the remainder to the next component. Repeat the process until there are no components remaining.

The notation used by humans for long division is...

$\begin{array}{l}\phantom{{{divisor}\smash{)}}}{{quotient}} \{{divisor}}\overline{\smash{)}{dividend}} \\end{array}$

For example, long division notation for 752 / 3 is initially written as...

$\begin{array}{l}\phantom{{{3}\smash{)}}}{{}} \{{3}}\overline{\smash{)}{752}} \\end{array}$

Starting with the first component, divide (using idea 3) to get the quotient and remainder for that component: 200R100. Then, strip-off the trialing 0s and place the quotient on-top of the component and the remainder below the component...

$\begin{array}{l}\phantom{{{3}\smash{)}}}{{\green{2}}} \{{3}}\overline{\smash{)}{752}} \\phantom{{{3}\smash{)}}}{?} \\phantom{{{3}\smash{)}}}{\green{1}} \\end{array}$

A question mark is sandwiched between the component and remainder. The question mark should be set to the value of the divisor (3) multiplied by the quotient (200), with its trailing 0s stripped out. 3 * 200 = 600, strip the trialing 0s to get 6...

$\begin{array}{l}\phantom{{{3}\smash{)}}}{{2}} \{{3}}\overline{\smash{)}{752}} \\phantom{{{3}\smash{)}}}{\underline{\green{6}}} \\phantom{{{3}\smash{)}}}{1} \\end{array}$

Copy the next largest component down such that it's next the remainder...

$\begin{array}{l}\phantom{{{3}\smash{)}}}{{2}} \{{3}}\overline{\smash{)}{752}} \\phantom{{{3}\smash{)}}}{\underline{6}} \\phantom{{{3}\smash{)}}}{1\green{5}} \\end{array}$

This is effectively the same as adding the remainder to the next component: 100 + 50 = 150. Trailing 0s aren't seen because they're implied in long division notation.

Repeat the process but target the 15 at the bottom. The 15 is the next component rolled into the remainder...

$\begin{array}{l}\phantom{{{3}\smash{)}}}{{2\green{5}}} \{{3}}\overline{\smash{)}{752}} \\phantom{{{3}\smash{)}}}{\underline{6}} \\phantom{{{3}\smash{)}}}{15} \\phantom{{{3}\smash{)}}}{\underline{\green{15}}} \\phantom{{{3}\smash{)}}}{\phantom{0}\green{0}} \\end{array}$

Copy the next largest component down such that it's next the remainder...

$\begin{array}{l}\phantom{{{3}\smash{)}}}{{25}} \{{3}}\overline{\smash{)}{752}} \\phantom{{{3}\smash{)}}}{6} \\phantom{{{3}\smash{)}}}{15} \\phantom{{{3}\smash{)}}}{15} \\phantom{{{3}\smash{)}}}{\phantom{0}0\green{2}} \\end{array}$

Repeat the entire process but target the 2 at the bottom. The 2 is the next component rolled into the remainder...

$\begin{array}{l}\phantom{{{3}\smash{)}}}{{25\green{0}}} \{{3}}\overline{\smash{)}{752}} \\phantom{{{3}\smash{)}}}{\underline{6}} \\phantom{{{3}\smash{)}}}{15} \\phantom{{{3}\smash{)}}}{\underline{15}} \\phantom{{{3}\smash{)}}}{\phantom{0}02} \\phantom{{{3}\smash{)}}}{\phantom{00}\underline{\green{0}}} \\phantom{{{3}\smash{)}}}{\phantom{00}\green{2}} \\end{array}$

The final reminder isn't 0, so place it next to the final quotient...

$\begin{array}{l}\phantom{{{3}\smash{)}}}{{250\green{R2}}} \{{3}}\overline{\smash{)}{752}} \\phantom{{{3}\smash{)}}}{\underline{6}} \\phantom{{{3}\smash{)}}}{15} \\phantom{{{3}\smash{)}}}{\underline{15}} \\phantom{{{3}\smash{)}}}{\phantom{0}02} \\phantom{{{3}\smash{)}}}{\phantom{00}\underline{0}} \\phantom{{{3}\smash{)}}}{\phantom{00}2} \\end{array}$

The way to perform this algorithm via code is as follows...

arithmetic_code/WholeNumber.py (lines 465 to 508):

@log_decorator
def __truediv__(dividend: WholeNumber, divisor: WholeNumber) -> (WholeNumber, WholeNumber):
    if divisor == WholeNumber.from_int(0):
        raise Exception('Cannot divide by 0')

    log(f'Dividing {dividend} by {divisor}...')
    log_indent()

    count = len(dividend.digits)

    quot = WholeNumber.from_int(0)
    rem = WholeNumber.from_int(0)
    for pos in reversed(range(0, count)):  # from largest to smallest component
        log(f'Targeting dividend: {dividend._highlight(pos)}, Current quotient: {quot} / Current remainder: {rem}')
        log_indent()

        comp = dividend[pos]
        if pos == count - 1:  # if this is the start component (largest component)...
            comp_dividend = WholeNumber.from_digit(comp)
            log(f'Set dividend: component ({comp}): {comp_dividend}')
        else:
            temp_rem = rem.copy()
            temp_rem.shift_left(1)
            comp_dividend = WholeNumber.from_digit(comp) + temp_rem
            log(f'Set dividend: Combining prev remainder ({rem}) with component ({comp}): {comp_dividend}')

        comp_quot, comp_rem = WholeNumber.trial_and_error_div(comp_dividend, divisor)
        log(f'Trial-and-error division: {comp_dividend} / {divisor} = {comp_quot}R{comp_rem}')

        new_quot = quot.copy()
        new_quot.shift_left(1)
        new_quot[0] = comp_quot[0]  # comp_quot will always be a single digit
        log(f'New quotient: Combining existing quotient ({quot}) with ({comp_quot}): {new_quot}')
        log(f'New remainder: {comp_rem}')
        quot = new_quot
        rem = comp_rem

        log_unindent()

    log_unindent()
    log(f'Final Quotient: {quot}, Final Remainder: {rem}')

    return quot, rem

Word Conversion

Whole number word conversion is the process of taking a whole number and converting it to words. To convert a whole number to words, break up the number into groups of 3 from least-significant digit to most-significant digit (right-to-left). For example, the number 9876543210 gets broken up as follows...

For each group, use the following algorithm to construct the words to represent that group:

• If top digit exists, use the following mapping:

  Digit	Word
  0
  1	one hundred
  2	two hundred
  3	three hundred
  4	four hundred
  5	five hundred
  6	six hundred
  7	seven hundred
  8	eight hundred
  9	nine hundred

  

• If middle digit is 1, combine in with the bottom digit and use the following mapping:

  Digits	Word
  10	ten
  11	eleven
  12	twelve
  13	thirteen
  14	fourteen
  15	fifteen
  16	sixteen
  17	seventeen
  18	eighteen
  19	nineteen

  

• If the middle digit isn't 1, use the following mapping:

  Digit	Word
  0
  2	twenty
  3	thirty
  4	forty
  5	fifty
  6	sixty
  7	seventy
  8	eighty
  9	ninety

  

• If the middle digit wasn't 1, use the following mapping for the bottom digit:

  Digit	Word
  0
  1	one
  2	two
  3	three
  4	four
  5	five
  6	six
  7	seven
  8	eight
  9	nine

  

In the example above, each group would get converted as follows...

The words for each group get a special suffix. For each group from right-to-left, ...

In the example above, each group would get its corresponding suffix added...

There is one special case with number to word conversions: if the number being converted is 0, the output should be zero.

The way to perform this algorithm via code is as follows...

arithmetic_code/WholeNumber.py (lines 718 to 850):

@log_decorator
def to_words(self: WholeNumber) -> str:
    suffixes = [None, 'thousand', 'million', 'billion', 'trillion', 'quadrillion', 'quintillion']

    log(f'Converting {self}...')
    log_indent()

    output = ''

    digits_copy = self.digits[:]
    while not digits_copy == []:
        d1 = digits_copy.pop(0) if digits_copy != [] else None
        d2 = digits_copy.pop(0) if digits_copy != [] else None
        d3 = digits_copy.pop(0) if digits_copy != [] else None

        log(f'Converting group {d3} {d2} {d1}...')
        log_indent()

        txt = ''
        if d3 is not None and d3 != Digit(0):
            if d3.value == Digit(1):
                txt += 'one hundred'
            elif d3.value == Digit(2):
                txt += 'two hundred'
            elif d3.value == Digit(3):
                txt += 'three hundred'
            elif d3.value == Digit(4):
                txt += 'four hundred'
            elif d3.value == Digit(5):
                txt += 'five hundred'
            elif d3.value == Digit(6):
                txt += 'six hundred'
            elif d3.value == Digit(7):
                txt += 'seven hundred'
            elif d3.value == Digit(8):
                txt += 'eight hundred'
            elif d3.value == Digit(9):
                txt += 'nine hundred'
            else:
                raise Exception()

        ignore_first_digit = False
        if d2 is not None and d3 != Digit(0):
            txt += ' '
            if d2.value == Digit(1):
                ignore_first_digit = True
                if d1 == Digit(0):
                    txt += 'ten'
                elif d1 == Digit(1):
                    txt += 'eleven'
                elif d1 == Digit(2):
                    txt += 'twelve'
                elif d1 == Digit(3):
                    txt += 'thirteen'
                elif d1 == Digit(4):
                    txt += 'fourteen'
                elif d1 == Digit(5):
                    txt += 'fifteen'
                elif d1 == Digit(6):
                    txt += 'sixteen'
                elif d1 == Digit(7):
                    txt += 'seventeen'
                elif d1 == Digit(8):
                    txt += 'eighteen'
                elif d1 == Digit(9):
                    txt += 'nineteen'
                else:
                    raise Exception()
            elif d2.value == Digit(2):
                txt += 'twenty'
            elif d2.value == Digit(3):
                txt += 'thirty'
            elif d2.value == Digit(4):
                txt += 'forty'
            elif d2.value == Digit(5):
                txt += 'fifty'
            elif d2.value == Digit(6):
                txt += 'sixty'
            elif d2.value == Digit(7):
                txt += 'seventy'
            elif d2.value == Digit(8):
                txt += 'eighty'
            elif d2.value == Digit(9):
                txt += 'ninety'
            else:
                raise Exception()

        if not ignore_first_digit and d1 is not None and d1 != Digit(0):
            txt += ' '
            if d1.value == Digit(1):
                txt += 'one'
            elif d1.value == Digit(2):
                txt += 'two'
            elif d1.value == Digit(3):
                txt += 'three'
            elif d1.value == Digit(4):
                txt += 'four'
            elif d1.value == Digit(5):
                txt += 'five'
            elif d1.value == Digit(6):
                txt += 'six'
            elif d1.value == Digit(7):
                txt += 'seven'
            elif d1.value == Digit(8):
                txt += 'eight'
            elif d1.value == Digit(9):
                txt += 'nine'
            else:
                raise Exception()

        if suffixes == []:
            raise Exception('Number too large')

        log(f'Words: {txt}')

        suffix = suffixes.pop(0)
        if suffix is not None:
            txt += ' ' + suffix

        log(f'Suffix: {suffix}')
        log_unindent()

        output = txt + ' ' + output

    output = output.lstrip()
    if output == '':
        output = 'zero'

    log_unindent()
    log(f'{output}')

    return output.strip()

Integer Number

Integer numbers are place-value notation numbers that have no fractional part but are mirrored across 0. That is, think of integers as 2 sets of counting numbers separated by 0, where everything to the...

• right of 0 is called a positive number (signified by a + prefix)
• left of 0 is called a negative number (signified by a - prefix)

The prefix that determines if a integer is positive or negative is referred to as the sign. All numbers other than 0 have a sign. 0 represents nothing / no value, which is why it doesn't have a sign -- it's used as a separation point between the positive and negative values.

Conceptually, you can think of the positives the same way you think about natural numbers. They represent some value. For each positive, there's a corresponding negative that represents the opposite of that positive value. For example, if...

• positive integers represent steps forward, then negative integers would represent steps backward.

  • walk 5 steps (go forward 5 steps)
  • walk -5 steps (go backward 5 steps)

  

• positive integers represent money gained, then negative integers would represent money owed or spent.

  • 5 dollars (gain $5)
  • -5 dollars (spend $5, or be in debt $5)

  

• positive integers represent depth below sea-level, then negative integers would represent elevation above sea-level.

  • depth of 5 meters (5 meters below sea-level)
  • depth of -5 meters (5 meters above sea-level)

  

Equality

Integer equality is an extension of whole number equality. In whole number equality, the digit at each position must match between the numbers being compared. Integer equality adds an extra stipulation: the sign of the number must match as well.

For example, the numbers -195 and 195 are not equal...

- 1 9 5
x | | |
+ 1 9 5

... while the numbers -195 and -195 are equal...

- 1 9 5
| | | |
- 1 9 5

The way to perform this algorithm via code is as follows...

arithmetic_code/IntegerNumber.py (lines 211 to 229):

@log_decorator
def __eq__(self: IntegerNumber, other: IntegerNumber) -> bool:
    log(f'Equality testing {self} and {other}...')
    log_indent()

    log(f'Testing sign equality ({self.sign} vs {other.sign})...')
    sign_eq = self.sign == other.sign
    log(f'{sign_eq}')

    log(f'Testing magnitude equality ({self.magnitude} vs {other.magnitude})...')
    mag_eq = self.magnitude == other.magnitude
    log(f'{mag_eq}')

    log_unindent()
    ret = sign_eq and mag_eq
    log(f'{ret}')

    return ret

Less Than

Recall that the number line for integers is more complex than the number line for whole numbers. The negatives and positives mirror at 0 and they grow in opposite directions:

• positive numbers grow as you move right-ward (e.g. 1, 2, 3, ...).
• negative numbers grow as you move left-ward (e.g. ..., -3, -2, -1).

The algorithm for integer less than applies different logic depending on the sign of each number. Specifically, if the numbers are...

• both non-negative, apply the whole number less than algorithm. For example, 2 < 5 would be processed just as if it were a whole number...

  

  ⚠️NOTE️️️⚠️

  Non-negative includes both 0 and positive numbers.

• both non-positive, switch the negative sign to positive sign and apply the whole number greater than algorithm. For example, -5 < -2 would become 5 > 2...

  

  After switching sign, the number being tested (5) is to the right of the other number (2). 5 > 2 would be processed just as if it were a whole number.

  ⚠️NOTE️️️⚠️

  Non-positive includes both 0 and negative numbers.

• negative and positive, return true only if the negative number is the one being tested. For example, 2 < -4 is false because 2 (the number being tested) isn't negative...

  

The way to perform this algorithm via code is as follows...

arithmetic_code/IntegerNumber.py (lines 232 to 263):

@log_decorator
def __lt__(self: IntegerNumber, other: IntegerNumber) -> bool:
    log(f'Less than testing {self} and {other}...')
    log_indent()

    self_sign = self.sign
    if self_sign is None:  # assume 0 is a positive -- it simplifies logic below
        self_sign = Sign.POSITIVE

    other_sign = other.sign
    if other_sign is None:  # assume 0 is a positive -- it simplifies logic below
        other_sign = Sign.POSITIVE

    if self_sign == Sign.POSITIVE and other_sign == Sign.POSITIVE:
        log(f'{self.sign} < {other.sign}: Applying whole number less than...')
        ret = self.magnitude < other.magnitude
    elif self_sign == Sign.NEGATIVE and other_sign == Sign.NEGATIVE:
        log(f'{self.sign} < {other.sign}: Turning positive and applying whole number greater than...')
        ret = self.magnitude > other.magnitude
    elif self_sign == Sign.POSITIVE and other_sign == Sign.NEGATIVE:
        log(f'{self.sign} < {other.sign}:: Different signs -- number being tested is positive...')
        ret = False
    elif self_sign == Sign.NEGATIVE and other_sign == Sign.POSITIVE:
        log(f'{self.sign} < {other.sign}: Different signs -- number being tested is negative...')
        ret = True
    log(f'{ret}')

    log_unindent()
    log(f'{ret}')

    return ret

Greater Than

Recall that the number line for integers is more complex than the number line for whole numbers. The negatives and positives mirror at 0 and they grow in opposite directions:

• positive numbers grow as you move right-ward (e.g. 1, 2, 3, ...).
• negative numbers grow as you move left-ward (e.g. ..., -3, -2, -1).

The algorithm for integer greater than applies different logic depending on the sign of each number. Specifically, if the numbers are...

• both non-negative, apply the whole number greater than algorithm. For example, 5 > 2 would be processed just as if it were a whole number...

  

  ⚠️NOTE️️️⚠️

  Non-negative includes both 0 and positive numbers.

• both non-positive, switch the negative sign to positive sign and apply the whole number less than algorithm. For example, -2 > -5 would become 2 < 5...

  

  After switching sign, the number being tested (2) is to the left of the other number (5). 2 < 5 would be processed just as if it were a whole number.

  ⚠️NOTE️️️⚠️

  Non-positive includes both 0 and negative numbers.

• negative and positive, return true only if the positive number is the one being tested. For example, 2 > -4 is true because 2 (the number being tested) is positive...

  

The way to perform this algorithm via code is as follows...

arithmetic_code/IntegerNumber.py (lines 269 to 300):

@log_decorator
def __gt__(self: IntegerNumber, other: IntegerNumber) -> bool:
    log(f'Greater than testing {self} and {other}...')
    log_indent()

    self_sign = self.sign
    if self_sign is None:  # assume 0 is a positive -- it simplifies logic below
        self_sign = Sign.POSITIVE

    other_sign = other.sign
    if other_sign is None:  # assume 0 is a positive -- it simplifies logic below
        other_sign = Sign.POSITIVE

    if self_sign == Sign.POSITIVE and other_sign == Sign.POSITIVE:
        log(f'{self.sign} > {other.sign}: Applying whole number less than...')
        ret = self.magnitude > other.magnitude
    elif self_sign == Sign.NEGATIVE and other_sign == Sign.NEGATIVE:
        log(f'{self.sign} > {other.sign}: Turning positive and applying whole number greater than...')
        ret = self.magnitude < other.magnitude
    elif self_sign == Sign.POSITIVE and other_sign == Sign.NEGATIVE:
        log(f'{self.sign} > {other.sign}:: Different signs -- number being tested is positive...')
        ret = True
    elif self_sign == Sign.NEGATIVE and other_sign == Sign.POSITIVE:
        log(f'{self.sign} > {other.sign}: Different signs -- number being tested is negative...')
        ret = False
    log(f'{ret}')

    log_unindent()
    log(f'{ret}')

    return ret

Addition

Conceptually, you can think of integer addition as movement on a number line. If some integer is being added to a...

• positive integer, it's moving right on the number line.

  For example, 3 + 4 is 7...

  

  For example, -5 + 4 is -1...

  

  Notice that the result of this example's movement is exactly the same as subtracting magnitudes, then tacking on a negative sign to the result: 5 - 4 is 1, tack on a negative sign to get -1.

• negative integer, it's moving left on the number line.

  For example, -1 + -4 is -5...

  

  Notice that the result of this example's movement is exactly the same as adding magnitudes, then tacking on a negative sign to the result: 1 + 4 is 5, tack on a negative sign to get -5.

  For example, 3 + -4 is -1...

  

  Notice that the result of this example's movement is exactly the same as swapping, subtracting, then tacking on a negative sign to the result: 4 - 3 is 1, tack on a negative sign: -1.

The algorithm used by humans to add integer numbers together revolves around inspecting the sign and magnitude of each integer, then deciding whether to perform whole number addition or whole number subtraction to get the result. The codification of this algorithm is as follows...

arithmetic_code/IntegerNumber.py (lines 50 to 82):

@log_decorator
def __add__(lhs: IntegerNumber, rhs: IntegerNumber) -> IntegerNumber:
    log(f'Adding {lhs} and {rhs}')
    log_indent()

    def determine_sign(magnitude: WholeNumber, default_sign: Sign) -> Sign:
        if magnitude == WholeNumber.from_int(0):
            return None
        else:
            return default_sign

    if lhs.sign is None:  # sign of None is only when magnitude is 0,  0 + a = a
        sign = rhs.sign
        magnitude = rhs.magnitude
    elif rhs.sign is None:  # sign of None is only when magnitude is 0,  a + 0 = a
        sign = lhs.sign
        magnitude = lhs.magnitude
    elif lhs.sign == rhs.sign:
        magnitude = lhs.magnitude + rhs.magnitude
        sign = determine_sign(magnitude, lhs.sign)
    elif lhs.sign != rhs.sign:
        if rhs.magnitude >= lhs.magnitude:
            magnitude = rhs.magnitude - lhs.magnitude
            sign = determine_sign(magnitude, rhs.sign)
        else:
            magnitude = lhs.magnitude - rhs.magnitude
            sign = determine_sign(magnitude, lhs.sign)

    log_unindent()
    log(f'sign: {sign}, magnitude: {magnitude}')

    return IntegerNumber(sign, magnitude)

Subtraction

Conceptually, you can think of integer subtraction as movement on a number line (opposite movement to that of integer addition). If the integer being subtracted by (right-hand side) is a...

• positive integer, it's moving left on the number line.

  For example, 5 - 4 = 1...

  

  For example, -2 - 4 = -6...

  

  Notice that the result of this example's movement is exactly the same as adding magnitudes, then tacking on a negative sign to the result: 2 + 4 = 6, tack on a negative sign to get -6.

  For example, 3 - 4 = -1...

  

  Notice that the result of this example's movement is exactly the same as swapping, subtracting, then tacking on a negative sign: 4 - 3 = 1, tack on a negative sign to get -1.

• negative integer, it's moving right on the number line.

  For example, 3 - -4 = 7...

  

  Notice that the result of this movement is exactly the same as performing 3 + 4.

  For example, -3 - -4 = 1...

  

  Notice that the result of this example's movement is exactly the same as swapping, subtracting, then tacking on a positive sign to the result: 4 - 3 = 1, tack on a positive sign: 1.

The algorithm used by humans to subtract integer numbers revolves around inspecting the sign and magnitude of each integer, then deciding whether to perform whole number addition or whole number subtraction to get the result. The codification of this algorithm is as follows...

arithmetic_code/IntegerNumber.py (lines 85 to 123):

@log_decorator
def __sub__(lhs: IntegerNumber, rhs: IntegerNumber) -> IntegerNumber:
    log(f'Subtracting {lhs} and {rhs}')
    log_indent()

    def determine_sign(magnitude: WholeNumber, default_sign: Sign) -> Sign:
        if magnitude == WholeNumber.from_int(0):
            return None
        else:
            return default_sign

    def flip_sign(sign: Sign) -> Sign:
        if sign == Sign.POSITIVE:
            return Sign.NEGATIVE
        elif sign == Sign.NEGATIVE:
            return Sign.POSITIVE

    if lhs.sign is None:  # sign of None is only when magnitude is 0,  0 - a = -a
        sign = flip_sign(rhs.sign)
        magnitude = rhs.magnitude
    elif rhs.sign is None:  # sign of None is only when magnitude is 0,  a - 0 = a
        sign = lhs.sign
        magnitude = lhs.magnitude
    elif lhs.sign == rhs.sign:
        if rhs.magnitude >= lhs.magnitude:
            magnitude = rhs.magnitude - lhs.magnitude
            sign = determine_sign(magnitude, flip_sign(lhs.sign))
        else:
            magnitude = lhs.magnitude - rhs.magnitude
            sign = determine_sign(magnitude, lhs.sign)
    elif lhs.sign != rhs.sign:
        magnitude = lhs.magnitude + rhs.magnitude
        sign = determine_sign(magnitude, lhs.sign)

    log_unindent()
    log(f'sign: {sign}, magnitude: {magnitude}')

    return IntegerNumber(sign, magnitude)

Multiplication

Conceptually, you can think of integer multiplication as repetitive integer addition / integer subtraction. When the right hand side is negative, think of it as subtraction instead of addition. For example, think of ...

• 5 * 3 as add 5, 3 times

• -5 * 3 as add -5, 3 times

• 3 * -5 as subtract 5, 3 times

  ⚠️NOTE️️️⚠️

  Subtraction starts from 0, so it'd be...

  1. 0 - 5 = -5
  2. -5 - 5 = -10
  3. -10 - 5 = -15

  Or, you could use the commutative property of multiplication and swap the operands -- 3 * -5 becomes -5 * 3, exactly the same as the previous bullet point.

• -5 * -3 as subtract -5, 3 times

  ⚠️NOTE️️️⚠️

  Subtraction starts from 0, so it'd be...

  1. 0 - -5 = 5
  2. -5 - -5 = 10
  3. -10 - -5 = 15

One useful property of integer multiplication is that, multiplying any non-zero number by -1 will slip its sign. For example...

• 5 * -1 = -5

  1. 0 - 5 = -5

• -5 * -1 = 5

  1. 0 - -5 = 5

The algorithms humans use to perform integer multiplication is as follows:

1. Ignoring the sign and multiply the numbers using whole number multiplication.
2. If the sign are...
   1. the same, make the result a positive.
   2. different, make the result a negative.

The result produced using the algorithm will be exactly the same as the result produced using repetitive addition/subtraction.

The way to perform this algorithm via code is as follows...

arithmetic_code/IntegerNumber.py (lines 126 to 156):

@log_decorator
def __mul__(lhs: IntegerNumber, rhs: IntegerNumber) -> IntegerNumber:
    log(f'Multiplying {lhs} and {rhs}')
    log_indent()

    def determine_sign(magnitude: WholeNumber, default_sign: Sign) -> Sign:
        if magnitude == WholeNumber.from_int(0):
            return None
        else:
            return default_sign

    if lhs.sign is None:  # when sign isn't set, magnitude is always 0 -- 0 * a = 0
        sign = None
        magnitude = WholeNumber.from_int(0)
    elif rhs.sign is None:  # when sign isn't set, magnitude is always 0 -- a * 0 = 0
        sign = None
        magnitude = WholeNumber.from_int(0)
    elif (lhs.sign == Sign.POSITIVE and rhs.sign == Sign.POSITIVE) \
            or (lhs.sign == Sign.NEGATIVE and rhs.sign == Sign.NEGATIVE):
        magnitude = lhs.magnitude * rhs.magnitude
        sign = determine_sign(magnitude, Sign.POSITIVE)
    elif (lhs.sign == Sign.POSITIVE and rhs.sign == Sign.NEGATIVE) \
            or (lhs.sign == Sign.NEGATIVE and rhs.sign == Sign.POSITIVE):
        magnitude = lhs.magnitude * rhs.magnitude
        sign = determine_sign(magnitude, Sign.NEGATIVE)

    log_unindent()
    log(f'sign: {sign}, magnitude: {magnitude}')

    return IntegerNumber(sign, magnitude)

Division

Conceptually, you can think of integer division the same as whole number division: repetitive integer subtraction -- how many iterations can be subtracted until reaching 0. When both numbers being divided have the same sign, the process is nearly the same as whole number division. For example, ...

• 15 / 3 -- how many iterations og subtracting by 3 before 15 reaches 0

  

  You need to subtract by 3 to get closer to 0...

  1. 15 - 3 = -12
  2. 12 - 3 = -9
  3. 9 - 3 = -6
  4. 6 - 3 = -3
  5. 3 - 3 = 0

  5 iterations of subtraction.

• -15 / -3 -- how many iterations of subtracting by -3 before -15 reaches 0

  

  You need to subtract by -3 to get closer to 0...

  1. -15 - -3 = -12
  2. -12 - -3 = -9
  3. -9 - -3 = -6
  4. -6 - -3 = -3
  5. -3 - -3 = 0

  5 iterations of subtraction.

When the sign are different, it becomes slightly more difficult to conceptualize. For example, using repetitive subtraction on -15 / 3 will get farther from 0 rather than closer:

1. -15 - 3 = -18
2. -18 - 3 = -21
3. -21 - 3 = -24
4. ...

In cases such as this, the concept of negative iterations is needed. For example, when ...

• subtracting by 5 iterations, you iteratively subtract for 5 iterations.
• subtracting by -5 iterations, you iteratively add for 5 iterations.

Why? The inverse (opposite) of subtraction is addition. Performing -5 iterations means doing the opposite for 5 iterations.

• -15 / 3 -- how many iterations of subtracting by 3 before -15 reaches 0

  

  You need to add by 3 to get closer to 0...

  1. -15 + 3 = -12
  2. -12 + 3 = -9
  3. -9 + 3 = -6
  4. -6 + 3 = -3
  5. -3 + 3 = 0

  -5 iterations of subtraction.

• 15 / -3 -- how many iterations of subtracting by -3 before 15 reaches 0

  

  You need to add by -3 to get closer to 0...

  1. 15 + -3 = 12
  2. 12 + -3 = 9
  3. 9 + -3 = 6
  4. 6 + -3 = 3
  5. 3 + -3 = 0

  -5 iterations of subtraction.

The algorithms humans use to perform integer multiplication is as follows:

1. Ignoring the sign and divide the numbers using whole number division.
2. If the sign are...
   1. the same, make the result a positive.
   2. different, make the result a negative.

The result produced using the algorithm will be exactly the same as the result produced using repetitive subtraction.

The way to perform this algorithm via code is as follows...

arithmetic_code/IntegerNumber.py (lines 159 to 192):

@log_decorator
def __truediv__(lhs: IntegerNumber, rhs: IntegerNumber) -> (IntegerNumber, IntegerNumber):
    log(f'Dividing {lhs} and {rhs}')
    log_indent()

    def determine_sign(magnitude: WholeNumber, default_sign: Sign) -> Sign:
        if magnitude == WholeNumber.from_int(0):
            return None
        else:
            return default_sign

    if lhs.sign is None:  # when sign isn't set, magnitude is always 0 -- 0 / a = 0
        (quotient_magnitude, remainder_magnitude) = lhs.magnitude / rhs.magnitude
        quotient_sign = None
        remainder_sign = None
    elif rhs.sign is None:  # when sign isn't set, magnitude is always 0 -- a / 0 = err
        raise Exception('Cannot divide by 0')
    elif (lhs.sign == Sign.POSITIVE and rhs.sign == Sign.POSITIVE) \
            or (lhs.sign == Sign.NEGATIVE and rhs.sign == Sign.NEGATIVE):
        (quotient_magnitude, remainder_magnitude) = lhs.magnitude / rhs.magnitude
        quotient_sign = determine_sign(quotient_magnitude, Sign.POSITIVE)
        remainder_sign = determine_sign(remainder_magnitude, Sign.POSITIVE)
    elif (lhs.sign == Sign.POSITIVE and rhs.sign == Sign.NEGATIVE) \
            or (lhs.sign == Sign.NEGATIVE and rhs.sign == Sign.POSITIVE):
        (quotient_magnitude, remainder_magnitude) = lhs.magnitude / rhs.magnitude
        quotient_sign = determine_sign(quotient_magnitude, Sign.NEGATIVE)
        remainder_sign = determine_sign(remainder_magnitude, Sign.NEGATIVE)

    log_unindent()
    log(f'QUOTIENT: sign: {quotient_sign}, magnitude: {quotient_magnitude}')
    log(f'REMAINDER: sign: {remainder_sign}, magnitude: {remainder_magnitude}')

    return IntegerNumber(quotient_sign, quotient_magnitude), IntegerNumber(remainder_sign, remainder_magnitude)

Word Conversion

Integer word conversion is the process of taking an integer number and converting it to words. The algorithm used by humans to convert an integer number to words is as follows:

Begin by converting the sign to a word. If the number is ...

• negative, use the word "negative".
• 0 or positive, ignore.

Then, write out the actual number as you would during whole number word conversion.

For example, the number...

• -9 ⟶ negative nine
• 9 ⟶ nine
• -55139 ⟶ negative fifty five thousand one hundred thirty nine
• 0 ⟶ zero

The way to perform this algorithm via code is as follows...

arithmetic_code/IntegerNumber.py (lines 195 to 208):

@log_decorator
def to_words(self: IntegerNumber) -> str:
    log(f'Converting {self}...')

    output = ''
    if self.sign == Sign.NEGATIVE:
        output += 'negative '
    output += self.magnitude.to_words()

    log_unindent()
    log(f'{output}')

    return output.lstrip()

Multiple

Imagine that you have the integer numbers n and m (use the letters as placeholders for some arbitrary integer numbers). m is a multiple of n if some integer exists such that $n \cdot ? = m$.

For example, the multiples of 2 are...

• 2*0=2 -- 0 is a multiple of 2

• 2*1=2 -- 2 is a multiple of 2

  ┌──┐
  │●●│ 2 can be grouped as 1 group of 2
  └──┘
  

• 2*2=4 -- 4 is a multiple of 2

  ┌──┬──┐
  │●●│●●│ 4 can be grouped as 2 groups of 2
  └──┴──┘
  

• 2*3=6 -- 6 is a multiple of 2

  ┌──┬──┬──┐
  │●●│●●│●●│ 6 can be grouped as 3 groups of 2
  └──┴──┴──┘
  

• 2*4=8 -- 8 is a multiple of 2

  ┌──┬──┬──┬──┐
  │●●│●●│●●│●●│ 8 can be grouped as 4 groups of 2
  └──┴──┴──┴──┘
  

• etc..

A number like 7 wouldn't be a multiple of 2 because there is no integer that can be multiplied by 2 to get 7 -- 2*3.5=7, but 3.5 isn't an integer.

┌──┬──┬──┬─┐
│●●│●●│●●│●│ 7 can't be grouped as groups of 2 (last group only has 1)
└──┴──┴──┴─┘

Divisible

Imagine that you have the integer numbers d and n (use the letters as placeholders for some arbitrary integer numbers). d is divisible by n if $d \div n$ has a remainder of 0.

For example, 8 is divisible by...

• 8/1=8 -- 8 is divisible by 1

  ┌────────┐
  │●●●●●●●●│ 8 can be grouped as 1 group of 8
  └────────┘
  

• 8/2=4 -- 8 is divisible by 2

  ┌────┬────┐
  │●●●●│●●●●│ 8 can be grouped as 2 groups of 4
  └────┴────┘
  

• 8/4=2 -- 8 is divisible by 4

  ┌──┬──┬──┬──┐
  │●●│●●│●●│●●│ 8 can be grouped as 4 groups of 2
  └──┴──┴──┴──┘
  

• 8/8=1 -- 8 is divisible by 8

  ┌─┬─┬─┬─┬─┬─┬─┬─┐
  │●│●│●│●│●│●│●│●│ 8 can be grouped as 8 groups of 1
  └─┴─┴─┴─┴─┴─┴─┴─┘
  

In all of the above cases, there is no remainder. 8 wouldn't be divisible by a number like 3 because there would be a remainder. 8/3=2R2.

┌───┬───┬──┐
│●●●│●●●│●●│ 8 can't be grouped as groups of 3 (last group only has 2)
└───┴───┴──┘

Common divisibility tests are simple tests you can do on a number to see if its divisible. To see if a number is divisible by...

• 2, check if the last digit is either 0, 2, 4, 6, or 8.

  1	2	3	4	5	6	7	8	9	10
  11	12	13	14	15	16	17	18	19	20
  21	22	23	24	25	26	27	28	29	30
  31	32	33	34	35	36	37	38	39	40
  41	42	43	44	45	46	47	48	49	50

• 5, check if the last digit is either 5 or 0.

  1	2	3	4	5	6	7	8	9	10
  11	12	13	14	15	16	17	18	19	20
  21	22	23	24	25	26	27	28	29	30
  31	32	33	34	35	36	37	38	39	40
  41	42	43	44	45	46	47	48	49	50

• 10, check if the last digit is 0.

  1	2	3	4	5	6	7	8	9	10
  11	12	13	14	15	16	17	18	19	20
  21	22	23	24	25	26	27	28	29	30
  31	32	33	34	35	36	37	38	39	40
  41	42	43	44	45	46	47	48	49	50

• 3, sum up the individual digits and check if divisibly by 3.

  This is a recursive operation. For example...

  • 6
    • 6 is a multiple of 3
  • 36363,
    • 3+6+3+6+3=21,
      • 2+1=3
        • 3 is a multiple of 3

  Keep doing it until you get a 1 digit answer and check to see if that answer is either 3, 6, or 9.

  1	2	3	4	5	6	7	8	9	10
  11	12	13	14	15	16	17	18	19	20
  21	22	23	24	25	26	27	28	29	30
  31	32	33	34	35	36	37	38	39	40
  41	42	43	44	45	46	47	48	49	50
  51	52	53	54	55	56	57	58	59	60

• 6, apply common divisibility tests for 2 and 3, they both must pass.

  1	2	3	4	5	6	7	8	9	10
  11	12	13	14	15	16	17	18	19	20
  21	22	23	24	25	26	27	28	29	30
  31	32	33	34	35	36	37	38	39	40
  41	42	43	44	45	46	47	48	49	50
  51	52	53	54	55	56	57	58	59	60

  ⚠️NOTE️️️⚠️

  The bold numbers in the table above are numbers that appear bold in both the table for 2s and the table for 3s -- they must be bold in both tables.